linux-kernel - [PATCH] kernel-doc: document object-like preprocessor macros

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20240109140345.3344094-1-daniel.vetter@ffwll.ch>
Date: Tue,  9 Jan 2024 15:03:45 +0100
From: Daniel Vetter <daniel.vetter@...ll.ch>
To: LKML <linux-kernel@...r.kernel.org>
Cc: DRI Development <dri-devel@...ts.freedesktop.org>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Randy Dunlap <rdunlap@...radead.org>,
	Thomas Zimmermann <tzimmermann@...e.de>,
	Maxime Ripard <mripard@...nel.org>,
	"Steven Rostedt (Google)" <rostedt@...dmis.org>,
	Jonathan Corbet <corbet@....net>,
	linux-doc@...r.kernel.org,
	Daniel Vetter <daniel.vetter@...el.com>
Subject: [PATCH] kernel-doc: document object-like preprocessor macros

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@infradead.org/
Cc: Randy Dunlap <rdunlap@...radead.org>
Cc: Thomas Zimmermann <tzimmermann@...e.de>
Cc: Maxime Ripard <mripard@...nel.org>
Cc: Daniel Vetter <daniel.vetter@...ll.ch>
Cc: "Steven Rostedt (Google)" <rostedt@...dmis.org>
Cc: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@...el.com>
---
 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