Add some documentation for the functions we have defined here

Since we want to have maintainable code.

diff --git a/turbot.py b/turbot.py
index b8e3da2d9f17b7936006910f00c3fe48e4de81d6..bfc07e3e0af13e04fcfa63e5292bb971fb75e174 100755 (executable)
--- a/turbot.py
+++ b/turbot.py
@@ -18,6 +18,13 @@ slack_events = SlackEventAdapter(slack_signing_secret, "/slack/events", app)
 slack_client = WebClient(slack_bot_token)
 
 def rot_string(str, n=13):
+    """Return a rotated version of a string
+
+    Specifically, this functions returns a version of the input string
+    where each uppercase letter has been advanced 'n' positions in the
+    alphabet (wrapping around). Lowercase letters and any non-alphabetic
+    characters will be unchanged."""
+
     result = ''
     for letter in str:
         if letter.isupper():
@@ -28,6 +35,23 @@ def rot_string(str, n=13):
 
 @app.route('/rot', methods = ['POST'])
 def rot():
+    """Implements the /rot route for the /rot slash command in Slack
+
+    This implements the /rot command of our Slack bot. The format of this
+    command is as follows:
+
+       /rot [count|*] String to be rotated
+
+    The optional count indicates an amount to rotate each character in the
+    string. If the count is '*' or is not present, then the string will
+    be rotated through all possible 25 values.
+
+    The result of the rotation is provided as a message in Slack. If the
+    slash command was issued in a direct message, the response is made by
+    using the "response_url" from the request. This allows the bot to reply
+    in a direct message that it is not a member of. Otherwise, if the slash
+    command was issued in a channel, the bot will reply in that channel."""
+
     response_url = request.form.get('response_url')
     channel_name = request.form.get('channel_name')
     channel = request.form.get('channel_id')