[Linux-kernel-mentees] Investigating parsing error for struct/union

Jonathan Corbet corbet at lwn.net
Mon Feb 22 21:49:22 UTC 2021

Lukas Bulwahn <lukas.bulwahn at gmail.com> writes:

> Aditya, I independently made a similar observation and noted this
> issue in my personal notes, which will serve for a cleanup patch
> series, as follows:
> The kernel-doc should proceed the code, and the required definition of
> data structures should stay close to the function in between the
> kernel-doc comment and the function definition.
> Let kernel-doc know to skip certain definitions; the actual definition
> documented will follow directly after the skipped definitions.
> E.g.,
> include/linux/cgroup.h:450: task_css_set_check: SKIP DEFINITIONS
> (struct mutex cgroup_mutex; spinlock_t css_set_lock)
> include/linux/hid-sensor-hub.h:174:
> sensor_hub_input_attr_get_raw_value: SKIP DEFINITIONS (enum
> sensor_hub_read_flags)
> I have not thought about a good syntax for that:
> maybe something like:
> /**
> * foo - description
> *
> * @arg: description
> *
> * ::skip: struct bar, enum blub, define MACRO
> */
> where "::" serves as some annotation to instruct kernel-doc

Honestly, we will never get that sort of annotation into the source
without encountering substantial pushback, and it will also be hard to
keep them up to date.  I don't see that as being the right path forward.

The better solution, for now, would be to just insist that the kerneldoc
comments be next to the thing they are describing, and to submit patches
fixing these issues to the appropriate maintainers.  Mauro and others
have been doing a fair amount of that already.

It might also be nice to make scripts/kernel-doc smarter so that it can
handle any degree of separation between the comment and the
declaration.  But that would complicate an already gnarly script for
(IMO) relatively little gain.



More information about the Linux-kernel-mentees mailing list