Messages in this thread | | | Date | Wed, 15 Jul 2020 13:32:36 +0530 | From | Viresh Kumar <> | Subject | Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling_rate() header to standard comment block |
| |
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
| |