scripts: gen_defines.py: Improve output formatting and shorten main()

Make the node/ordinal list a part of the header comment to make the
output prettier.

Before:

    /*
     * Generated by gen_defines.py
     *
     * DTS input file:
     *   rv32m1_vega_ri5cy.dts.pre.tmp
     *
     * Directories with bindings:
     *   $ZEPHYR_BASE/dts/bindings
     */

    /* Nodes in dependency order (ordinal : path): */
    /* 0 : / */
    /* 1 : /aliases */
    /* 2 : /chosen */
    /* 3 : /connector */
    /* 4 : /cpus */
    /* 5 : /cpus/cpu@0 */
    /* 6 : /gpio_keys */
    /* 7 : /soc */
    ...

After:

    /*
     * Generated by gen_defines.py
     *
     * DTS input file:
     *   rv32m1_vega_ri5cy.dts.pre.tmp
     *
     * Directories with bindings:
     *   $ZEPHYR_BASE/dts/bindings
     *
     * Nodes in dependency order (ordinal and path):
     *   0   /
     *   1   /aliases
     *   2   /chosen
     *   3   /connector
     *   4   /cpus
     *   5   /cpus/cpu@0
     *   6   /gpio_keys
     *   7   /soc
     *   ...
     */

Also move the writing of the top comment and the node comments into
separate functions, to shorten main() and make it easier to follow.

Piggyback some minor comment-related simplifications.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>

scripts/dts/gen_defines.py

@@ -40,25 +40,7 @@ def main():
     conf_file = open(args.conf_out, "w", encoding="utf-8")
     header_file = open(args.header_out, "w", encoding="utf-8")
 
-    out_comment("""\
-Generated by gen_defines.py
-
-DTS input file:
-  {}
-
-Directories with bindings:
-  {}""".format(
-    args.dts, ", ".join(map(relativize, args.bindings_dirs))
-), blank_before=False)
-
-    out_comment("Nodes in dependency order (ordinal : path):")
-    for scc in edt.scc_order():
-        if len(scc) > 1:
-            err("Cycle in devicetree involving: {}".format(
-                ", ".join([n.path for n in scc])))
-        node = scc[0]
-        out_comment("{} : {}".format(node.dep_ordinal, node.path),
-                    blank_before = False)
+    write_top_comment(edt)
 
     active_compats = set()
 
@@ -69,37 +51,7 @@ Directories with bindings:
             if node.matching_compat == "fixed-partitions":
                 continue
 
-            requires_text = ""
-            if node.depends_on:
-                requires_text = "Requires:\n"
-                for depends in node.depends_on:
-                    requires_text += "  {} {}\n".format(depends.dep_ordinal, depends.path)
-                requires_text += "\n"
-
-            supports_text = ""
-            if node.required_by:
-                supports_text = "Supports:\n"
-                for required in node.required_by:
-                    supports_text += "  {} {}\n".format(required.dep_ordinal, required.path)
-                supports_text += "\n"
-
-            out_comment("""\
-Devicetree node:
-  {}
-
-Binding (compatible = {}):
-  {}
-
-Dependency Ordinal: {}
-
-{}{}Description:
-{}""".format(
-    node.path, node.matching_compat, relativize(node.binding_path),
-    node.dep_ordinal, requires_text, supports_text,
-    # Indent description by two spaces
-    "\n".join("  " + line for line in node.description.splitlines())
-))
-
+            write_node_comment(node)
             write_regs(node)
             write_irqs(node)
             write_props(node)
@@ -130,8 +82,8 @@ Dependency Ordinal: {}
             write_flash_partition(node, flash_index)
             flash_index += 1
 
-    out_comment("Number of flash partitions")
     if flash_index != 0:
+        out_comment("Number of flash partitions")
         out("FLASH_AREA_NUM", flash_index)
 
     print("Devicetree configuration written to " + args.conf_out)
@@ -153,6 +105,62 @@ def parse_args():
     return parser.parse_args()
 
 
+def write_top_comment(edt):
+    # Writes an overview comment with misc. info at the top of the header and
+    # configuration file
+
+    s = """\
+Generated by gen_defines.py
+
+DTS input file:
+  {}
+
+Directories with bindings:
+  {}
+
+Nodes in dependency order (ordinal and path):
+""".format(edt.dts_path, ", ".join(map(relativize, edt.bindings_dirs)))
+
+    for scc in edt.scc_order():
+        if len(scc) > 1:
+            err("cycle in devicetree involving "
+                + ", ".join(node.path for node in scc))
+        s += "  {0.dep_ordinal:<3} {0.path}\n".format(scc[0])
+
+    out_comment(s, blank_before=False)
+
+
+def write_node_comment(node):
+    # Writes a comment describing 'node' to the header and configuration file
+
+    s = """\
+Devicetree node:
+  {}
+
+Binding (compatible = {}):
+  {}
+
+Dependency Ordinal: {}
+""".format(node.path, node.matching_compat, relativize(node.binding_path),
+           node.dep_ordinal)
+
+    if node.depends_on:
+        s += "\nRequires:\n"
+        for dep in node.depends_on:
+            s += "  {:<3} {}\n".format(dep.dep_ordinal, dep.path)
+
+    if node.required_by:
+        s += "\nSupports:\n"
+        for req in node.required_by:
+            s += "  {:<3} {}\n".format(req.dep_ordinal, req.path)
+
+    # Indent description by two spaces
+    s += "\nDescription:\n" + \
+         "\n".join("  " + line for line in node.description.splitlines())
+
+    out_comment(s)
+
+
 def relativize(path):
     # If 'path' is within $ZEPHYR_BASE, returns it relative to $ZEPHYR_BASE,
     # with a "$ZEPHYR_BASE/..." hint at the start of the string. Otherwise,
@@ -760,7 +768,7 @@ def out_comment(s, blank_before=True):
         for line in s.splitlines():
             # Avoid an extra space after '*' for empty lines. They turn red in
             # Vim if space error checking is on, which is annoying.
-            res.append(" *" if not line or line.isspace() else " * " + line)
+            res.append(" *" if not line.strip() else " * " + line)
         res.append(" */")
         print("\n".join(res), file=header_file)
     else: