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

[Lee Jones <lee.jones@linaro.org>]

On Wed, 15 Jul 2020, Viresh Kumar wrote:

> 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.

This will stop `scripts/find-unused-docs.sh` from mentioning these
files as an offender, but `scripts/kernel-doc` and by extension W=1
builds (which is the point of this patch-set) will still complain.

Before you add the lines above, you need to provide descriptions for
each of the function parameters or else they will not reach the
required standards expected of kerneldoc.

My suggestion would be to take this (and the other) patch and
subsequently provide your own set i) providing the required parameter
descriptions ii) re-promoting the comment blocks to kerneldoc and iii)
adding the aforementioned lines to the *.rst file(s).

> But the layout of things wont' be very nice right now.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog