[lbuild] Improve developer documentation

modm-io · Jul 8, 2019 · 3051c78 · 3051c78
1 parent 2ed0966
commit 3051c78
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 14 deletions.
diff --git a/ext/st/module.lb b/ext/st/module.lb
@@ -47,6 +47,15 @@ def getDefineForDevice(device_id, familyDefines):
 
 bprops = {}
 def common_rcc_map(env):
+    """
+    Finds all CMSIS bit fields related to enabling and resetting peripherals
+    in the RCC of the format `RCC_(REGISTER)_(PERIPHERAL)_(TYPE)` where:
+      - REGISTER: a variation of `(BUS)(ID?)(ENR|RSTR)`, e.g. `AHB1ENR`
+      - PERIPHERAL: typical peripheral name, e.g. `GPIOA`
+      - TYPE: either `EN` or `RST`.
+
+    :returns: a 2D-dictionary: map[PERIPHERAL][TYPE] = REGISTER
+    """
     device = env[":target"]
 
     core = device.get_driver("core")["type"]

diff --git a/tools/build_script_generator/common.py b/tools/build_script_generator/common.py
@@ -14,26 +14,46 @@
 import itertools
 from collections import defaultdict
 
-common_build_flags = [
-    "ccflags",
-    "cflags",
-    "cxxflags",
-    "asflags",
-    "archflags",
-    "linkflags",
-    "cppdefines",
-]
+common_build_flags = {
+    "ccflags": ("Compiler flags for both C and C++ sources",
+                ["See [Options that Control Optimization](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html)",
+                 "See [Options to Request or Suppress Warnings](https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html)",
+                 "See [Options for Debugging Your Program](https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html)"]),
+    "cflags": ("Compiler flags only for C sources",
+               ["See [Options Controlling C Dialect](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html)"]),
+    "cxxflags": ("Compiler flags only for C++ sources",
+                 ["See [Options Controlling C++ Dialect](https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html)"]),
+    "asflags": ("Assembler flags",
+                ["See [Assembler Options](https://gcc.gnu.org/onlinedocs/gcc/Assembler-Options.html)"]),
+    "archflags": ("Compiler flags related to the target architecture",
+                  ["See [Machine-Dependent Options](https://gcc.gnu.org/onlinedocs/gcc/Submodel-Options.html)"]),
+    "linkflags": ("Linker flags",
+                  ["See [Options for Linking](https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html)"]),
+    "cppdefines": ("Preprocessor definitions",
+                   ["Accepted values are `NAME` or `NAME=DEFINITION`.",
+                    "See `-D name=definition` in [Preprocessor Options](https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html)"]),
+}
 
 common_build_profiles = [
     "release",
     "debug",
 ]
 
-common_build_flag_names = [
-    flag+profile
+def _fmt_flag_descr(flag, profile):
+    flags = common_build_flags[flag]
+    descr = [flags[0], ""]
+    if len(profile):
+        descr[0] += " ({} profile)".format(profile[1:])
+    if "flags" in flag:
+        descr.append("Flags must start with '-'!")
+    descr += flags[1]
+    return "\n".join(descr)
+
+common_build_flag_names = {
+    flag+profile: _fmt_flag_descr(flag, profile)
         for flag in common_build_flags
             for profile in ([""] + ["."+p for p in common_build_profiles])
-]
+}
 
 def common_source_files(env):
     """

diff --git a/tools/build_script_generator/module.lb b/tools/build_script_generator/module.lb
@@ -117,9 +117,9 @@ def prepare(module, options):
         if not flag.startswith("-"):
             raise ValueError("Flags must start with '-'!")
         return flag
-    for name in common_build_flag_names:
+    for name, descr in common_build_flag_names.items():
         module.add_collector(
-            StringCollector(name=name, description=None,
+            StringCollector(name=name, description=descr,
                             validate=flag_validate if "flags" in name else None))
 
     return True