Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling_rate() header to standard comment block

[Viresh Kumar]

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