On Tue, Jan 9, 2024 at 9:16 AM Daniel Vetter <daniel.vetter@xxxxxxxx> 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@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> News to me as well. Acked-by: Alex Deucher <alexander.deucher@xxxxxxx> > --- > 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 >