On Tue, Jan 9, 2024 at 9:16 AM Daniel Vetter <daniel.vet...@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-39b6229ba...@infradead.org/ > Cc: Randy Dunlap <rdun...@infradead.org> > Cc: Thomas Zimmermann <tzimmerm...@suse.de> > Cc: Maxime Ripard <mrip...@kernel.org> > Cc: Daniel Vetter <daniel.vet...@ffwll.ch> > Cc: "Steven Rostedt (Google)" <rost...@goodmis.org> > Cc: Jonathan Corbet <cor...@lwn.net> > Cc: linux-...@vger.kernel.org > Signed-off-by: Daniel Vetter <daniel.vet...@intel.com>
News to me as well. Acked-by: Alex Deucher <alexander.deuc...@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 >