document with comments

comment.py

@@ -74,37 +74,54 @@ except NameError as e:
     print('failed to release memory', e)
 
 
+# init reusable walker and listener
 walker = ParseTreeWalker()
 listener = OscCommentMacroListener(servers)
 
 
+# main handler for processing input
 def comment(text):
+    # force upper case
     text = text.upper()
+    # generate text stream
     input_stream = InputStream(text)
+    # lex the text stream
     lexer = CommentMacroLexer(input_stream)
+    # get token stream from lexer
     stream = CommonTokenStream(lexer)
+    # parse the token steam
     parser = CommentMacroParser(stream)
+    # attach an error handler to the parser
     parser._listeners.append(SyntaxErrorListener())
     try:
+        # get tree from parser
         tree = parser.prog()
+        # walk the tree
         walker.walk(listener, tree)
     except SyntaxError as e:
         logger.debug(e)     # antlr internal listener prints the error
 #                           # log it to the debug logger anyway
 
 
+# handle user input if run directly
 if __name__ == '__main__':
     if len(sys.argv) > 1:
+        # look for macros passed as arguments
         logger.debug("found macro at argv[1]")
         comment(sys.argv[1])
     else:
-        import readline     # for input history and line editing
+        # for input history and line editing
+        import readline
+        # be an interactive shell
         while True:
+            # get user input
             try:
                 text = input("comment# ")
             except (KeyboardInterrupt, EOFError):
                 text = 'exit'
                 print(text)
+            # catch exit keyword
             if text.lower() == 'exit':
                 break
+            # exec user input
             comment(text)