On 15-07-20, 08:31, Lee Jones wrote: > I'm not sure what you mean. Kerneldoc headers are designed to be > extracted and converted into mediums which are easy to read/browse. > For example, see the online documentation for 'debug_object_init': > > > https://www.kernel.org/doc/html/latest/core-api/debug-objects.html?highlight=debug_object_init#c.debug_object_init > > They are generally meant to be referenced/consumed. There is even a > script provided inside the kernel to find offending instances where > kerneldoc headers are provided, but not *yet* referenced: > > `scripts/find-unused-docs.sh` > > HINT: There are many. > > There *could* be and argument to use kerneldoc *just* so you can use > the kerneldoc checker `scripts/kernel-doc` (which is invoked by W=1 > builds), in order to ensure the parameter descriptions are kept in > check. > > However, in this case, there are no descriptions provided. So, in > reference to my previous question, what are your reasons for wanting > to keep kerneldoc here?
I think the code did the right thing by keeping them as kernel doc type comments. What we missed then is getting them used in the *.rst documentation. A simple way of doing that could be just adding this to the cpu-freq rst file, like: -------------------------8<------------------------- Here are the bits from the in-source documentation: .. kernel-doc:: include/linux/cpufreq.h .. kernel-doc:: drivers/cpufreq/cpufreq.c .. kernel-doc:: drivers/cpufreq/freq_table.c .. kernel-doc:: drivers/cpufreq/cpufreq_governor.c -------------------------8<------------------------- This will make the script stop complaining about these. But the layout of things wont' be very nice right now. -- viresh
