Messages in this thread Patch in this message | ![/](/images/icornerl.gif) | | From | Daniel Vetter <> | Subject | [PATCH] kernel-doc: document object-like preprocessor macros | Date | Tue, 9 Jan 2024 15:03:45 +0100 |
| |
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@infradead.org> Cc: Thomas Zimmermann <tzimmermann@suse.de> Cc: Maxime Ripard <mripard@kernel.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: "Steven Rostedt (Google)" <rostedt@goodmis.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.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
| ![\](/images/icornerr.gif) |