Since 2014 kernel-doc has supported describing object-like macros macros but it is not documented anywhere. I should have required some documentation for it when I merged the patch. :( There are currently only 3 uses of this (all in DRM headers, in include/drm/*.h). There have recently been a few other attempts at using kernel-doc for object-like macros, but they didn't use the "define" keyword and I mistakenly told them that kernel-doc does not support such documentation. :( again. Add object-like kernel-doc documentation now so that more may know about it and use it. Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> Cc: Jonathan Corbet <corbet@xxxxxxx> Cc: linux-doc@xxxxxxxxxxxxxxx --- Documentation/doc-guide/kernel-doc.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff -- a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -341,6 +341,27 @@ Typedefs with function prototypes can al */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Object-like macro documentation +------------------------------- + +Object-like macros are distinct from function-like macros. They are +differentiated by whether the macro name is immediately followed by a +left parenthesis ('(') for function-like macros or not followed by one +for object-like macros. + +Function-like macros are handled like functions by ``scripts/kernel-doc``. +They may have a parameter list. Object-like macros have do not have a +parameter list. + +The general format of an object-like macro kernel-doc comment is:: + + /** + * define object_name - Brief description. + * + * Description of the object. + */ + + Highlights and cross-references -------------------------------