linux-kernel - Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200715081518.GA1398296@dell>
Date:   Wed, 15 Jul 2020 09:15:18 +0100
From:   Lee Jones <lee.jones@...aro.org>
To:     Viresh Kumar <viresh.kumar@...aro.org>
Cc:     rjw@...ysocki.net, linux-arm-kernel@...ts.infradead.org,
        linux-kernel@...r.kernel.org, linux-pm@...r.kernel.org,
        Venkatesh Pallipadi <venkatesh.pallipadi@...el.com>,
        Jun Nakajima <jun.nakajima@...el.com>,
        Alexander Clouter <alex@...riz.org.uk>
Subject: Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote
 store_sampling_rate() header to standard comment block

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