| Message ID | 20240109140345.3344094-1-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | kernel-doc: document object-like preprocessor macros | expand |
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 >
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
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 -------------------------------
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(+)