scripts: dts: gen_defines: don't include descriptions
Before we had a bindings index in the documentation, the generated
header file was (somewhat unfortunately) often our best reference for
what a particular binding or property within a binding ends up doing,
so it made good sense to put the description in the generated file.
Now that we have HTML documentation that's a bit more digestible than
the generated file, though, we can just point users at that. Do that
and remove the inline description from the generated file.
This makes it possible to put C-style multiline comments in the
descriptions themselves, which will be done in subsequent patches.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
diff --git a/scripts/dts/gen_defines.py b/scripts/dts/gen_defines.py
index e3466c7..0ce1164 100755
--- a/scripts/dts/gen_defines.py
+++ b/scripts/dts/gen_defines.py
@@ -248,11 +248,19 @@
"""
if node.description:
- # Indent description by two spaces
- s += "\nDescription:\n" + \
- "\n".join(" " + line for line in
- node.description.splitlines()) + \
- "\n"
+ # We used to put descriptions in the generated file, but
+ # devicetree bindings now have pages in the HTML
+ # documentation. Let users who are accustomed to digging
+ # around in the generated file where to find the descriptions
+ # now.
+ #
+ # Keeping them here would mean that the descriptions
+ # themselves couldn't contain C multi-line comments, which is
+ # inconvenient when we want to do things like quote snippets
+ # of .dtsi files within the descriptions, or otherwise
+ # include the string "*/".
+ s += ("\n(Descriptions have moved to the Devicetree Bindings Index\n"
+ "in the documentation.)\n")
out_comment(s)
