From 8b64fc8a5ec21c356b3dce3065cf06cdb95bc289 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beat=20K=C3=BCng?= <beat-kueng@gmx.net>
Date: Tue, 16 May 2017 10:05:14 +0200
Subject: [PATCH] Tools/px4moduledoc: add some comments, describe the regexes

---
 Tools/px4moduledoc/markdownout.py | 6 +++++-
 Tools/px4moduledoc/srcparser.py   | 5 +++--
 Tools/px4moduledoc/srcscanner.py  | 3 +++
 Tools/px4params/srcscanner.py     | 3 +++
 Tools/px_process_module_doc.py    | 2 +-
 5 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/Tools/px4moduledoc/markdownout.py b/Tools/px4moduledoc/markdownout.py
index 735489dd2d..dc01a47c98 100644
--- a/Tools/px4moduledoc/markdownout.py
+++ b/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 = {}
diff --git a/Tools/px4moduledoc/srcparser.py b/Tools/px4moduledoc/srcparser.py
index d02dfb7ef5..e34d4b1cd9 100644
--- a/Tools/px4moduledoc/srcparser.py
+++ b/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):
diff --git a/Tools/px4moduledoc/srcscanner.py b/Tools/px4moduledoc/srcscanner.py
index d4934b2d9c..e3c0aa5bec 100644
--- a/Tools/px4moduledoc/srcscanner.py
+++ b/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("\\", "/"))
 
diff --git a/Tools/px4params/srcscanner.py b/Tools/px4params/srcscanner.py
index 4db9d01ba7..38686c1e76 100644
--- a/Tools/px4params/srcscanner.py
+++ b/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("\\", "/"))
 
diff --git a/Tools/px_process_module_doc.py b/Tools/px_process_module_doc.py
index 2272fc0c00..569dc0cad7 100755
--- a/Tools/px_process_module_doc.py
+++ b/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)