* [PATCH] kernel-doc: document object-like preprocessor macros
@ 2024-01-09 14:03 Daniel Vetter
2024-01-09 14:59 ` Alex Deucher
2024-01-30 20:18 ` Jonathan Corbet
0 siblings, 2 replies; 3+ messages in thread
From: Daniel Vetter @ 2024-01-09 14:03 UTC (permalink / raw)
To: LKML
Cc: DRI Development, Daniel Vetter, Randy Dunlap, Thomas Zimmermann,
Maxime Ripard, Steven Rostedt (Google),
Jonathan Corbet, linux-doc, Daniel Vetter
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] kernel-doc: document object-like preprocessor macros
2024-01-09 14:03 [PATCH] kernel-doc: document object-like preprocessor macros Daniel Vetter
@ 2024-01-09 14:59 ` Alex Deucher
2024-01-30 20:18 ` Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Alex Deucher @ 2024-01-09 14:59 UTC (permalink / raw)
To: Daniel Vetter
Cc: LKML, Jonathan Corbet, DRI Development, Randy Dunlap, linux-doc,
Maxime Ripard, Steven Rostedt (Google),
Thomas Zimmermann, Daniel Vetter
On Tue, Jan 9, 2024 at 9:16 AM Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>
> 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>
News to me as well.
Acked-by: Alex Deucher <alexander.deucher@amd.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
>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] kernel-doc: document object-like preprocessor macros
2024-01-09 14:03 [PATCH] kernel-doc: document object-like preprocessor macros Daniel Vetter
2024-01-09 14:59 ` Alex Deucher
@ 2024-01-30 20:18 ` Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2024-01-30 20:18 UTC (permalink / raw)
To: Daniel Vetter, LKML
Cc: DRI Development, Daniel Vetter, Randy Dunlap, Thomas Zimmermann,
Maxime Ripard, Steven Rostedt (Google),
linux-doc, Daniel Vetter
Daniel Vetter <daniel.vetter@ffwll.ch> writes:
> 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(+)
Applied, thanks.
jon
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2024-01-30 20:18 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-01-09 14:03 [PATCH] kernel-doc: document object-like preprocessor macros Daniel Vetter
2024-01-09 14:59 ` Alex Deucher
2024-01-30 20:18 ` Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).