On Tue, Jan 9, 2024 at 9:16 AM Daniel Vetter <[email protected]> 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/[email protected]/ > Cc: Randy Dunlap <[email protected]> > Cc: Thomas Zimmermann <[email protected]> > Cc: Maxime Ripard <[email protected]> > Cc: Daniel Vetter <[email protected]> > Cc: "Steven Rostedt (Google)" <[email protected]> > Cc: Jonathan Corbet <[email protected]> > Cc: [email protected] > Signed-off-by: Daniel Vetter <[email protected]>
News to me as well. Acked-by: Alex Deucher <[email protected]> > --- > 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 >
