Tools/px4moduledoc: add some comments, describe the regexes

Tools/px4moduledoc/markdownout.py

@@ -1,8 +1,12 @@
+"""
+Class to generate Markdown documentation pages from parsed module doc strings
+"""
+
 from xml.sax.saxutils import escape
 import codecs
 import os
 
-class MarkdownTablesOutput():
+class MarkdownOutput():
     def __init__(self, module_groups):
 
         self._outputs = {}

Tools/px4moduledoc/srcparser.py

@@ -50,7 +50,7 @@ class ModuleDocumentation(object):
         self._category = self._get_string(args[1])
 
         self._usage_string = "%s <command> [arguments...]\n" % self._name
-	self._usage_string += " Commands:\n"
+        self._usage_string += " Commands:\n"
 
     def _handle_usage_name_simple(self, args):
         assert(len(args) == 2) # executable_name, category
@@ -200,7 +200,7 @@ class ModuleDocumentation(object):
     def documentation(self):
         doc_string = self._doc_string
 
-        # convert ' $ cmd' commands into code blocks
+        # convert '$ cmd' commands into code blocks (e.g. '$ logger start')
         # use lookahead (?=...) so the multiple consecutive command lines work
         doc_string = re.sub(r"\n\$ (.*)(?=\n)", r"\n```\n\1\n```", doc_string)
         # now merge consecutive blocks
@@ -240,6 +240,7 @@ class SourceParser(object):
     Parses provided data and stores all found parameters internally.
     """
 
+    # Regex to extract module doc function calls, starting with PRINT_MODULE_
     re_doc_definition = re.compile(r'PRINT_MODULE_([A-Z_]*)\s*\(')
 
     def __init__(self):

Tools/px4moduledoc/srcscanner.py

@@ -33,6 +33,9 @@ class SourceScanner(object):
         Scans provided file and passes its contents to the parser using
         parser.Parse method.
         """
+        # Extract the scope: it is the directory within the repo. Either it
+        # starts directly with 'src/module/abc', or it has the form 'x/y/z/src/module/abc'.
+        # The output is 'module/abc' in both cases.
         prefix = "^(|.*" + os.path.sep + ")src" + os.path.sep
         scope = re.sub(prefix.replace("\\", "/"), "", os.path.dirname(os.path.relpath(path)).replace("\\", "/"))
 

Tools/px4params/srcscanner.py

@@ -34,6 +34,9 @@ class SourceScanner(object):
         Scans provided file and passes its contents to the parser using
         parser.Parse method.
         """
+        # Extract the scope: it is the directory within the repo. Either it
+        # starts directly with 'src/module/abc', or it has the form 'x/y/z/src/module/abc'.
+        # The output is 'module/abc' in both cases.
         prefix = "^(|.*" + os.path.sep + ")src" + os.path.sep
         scope = re.sub(prefix.replace("\\", "/"), "", os.path.dirname(os.path.relpath(path)).replace("\\", "/"))
 

Tools/px_process_module_doc.py

@@ -96,7 +96,7 @@ def main():
         if (args.verbose): print("Creating markdown output to directory " + str(args.markdown))
         if not os.path.exists(args.markdown):
             os.makedirs(args.markdown)
-        out = markdownout.MarkdownTablesOutput(module_groups)
+        out = markdownout.MarkdownOutput(module_groups)
         out.Save(args.markdown)