I had no idea this exists, but Randy pointed out it's been added quite
a long time ago in cbb4d3e6510b ("scripts/kernel-doc: handle
object-like macros"). Definitely way before I started to write all the
drm docs sadly, so there's a few things where I skipped writing
kernel-doc since I didn't know it was possible.
Fix this asap by documenting the two possible kernel-doc flavours for
preprocessor definitions.
References: https://lore.kernel.org/dri-devel/dd917333-9ae8-4e76-991d-39b6229ba8ce@xxxxxxxxxxxxx/
Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Cc: Thomas Zimmermann <tzimmermann@xxxxxxx>
Cc: Maxime Ripard <mripard@xxxxxxxxxx>
Cc: Daniel Vetter <daniel.vetter@xxxxxxxx>
Cc: "Steven Rostedt (Google)" <rostedt@xxxxxxxxxxx>
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: linux-doc@xxxxxxxxxxxxxxx
Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
---
Documentation/doc-guide/kernel-doc.rst | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 6ad72ac6861b..a966f1fd5c30 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -341,6 +341,32 @@ Typedefs with function prototypes can also be documented::
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
+Preprocessor defines documentation
+----------------------------------
+
+There are two ways to document preprocessor defines. The first works more or
+less like kernel-doc for functions, including parameters::
+
+ /**
+ * FUNC_NAME() - Brief description
+ * @arg1: description of arg1
+ * @arg2: description of arg2
+ *
+ * Description of the preprocessor function, may have multiple paragraphs.
+ */
+ #define FUNC_NAME(arg1, arg2)
+
+The second type is different and for object-like preprocessor macros without any
+parameters::
+
+ /**
+ * define MACRO - Brief description
+ *
+ * Description of the object-like preprocessor macro, may have multiple
+ * paragraphs.
+ */
+ #define MACRO
+
Highlights and cross-references
-------------------------------
--
2.43.0
