Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx> 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: > > "SKIP DEFINITIONS" Feature: > > 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. Thanks, jon
