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]

Date:   Wed, 15 Jul 2020 12:38:36 +0530
From:   Viresh Kumar <viresh.kumar@...aro.org>
To:     Lee Jones <lee.jones@...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 15-07-20, 07:45, Lee Jones wrote:
> On Wed, 15 Jul 2020, Viresh Kumar wrote:
> > On 14-07-20, 15:50, Lee Jones wrote:
> > > diff --git a/drivers/cpufreq/cpufreq_governor.c b/drivers/cpufreq/cpufreq_governor.c
> > > index f99ae45efaea7..63f7c219062b9 100644
> > > --- a/drivers/cpufreq/cpufreq_governor.c
> > > +++ b/drivers/cpufreq/cpufreq_governor.c
> > > @@ -26,7 +26,7 @@ static DEFINE_PER_CPU(struct cpu_dbs_info, cpu_dbs);
> > >  static DEFINE_MUTEX(gov_dbs_data_mutex);
> > >  
> > >  /* Common sysfs tunables */
> > > -/**
> > > +/*
> > 
> > This is an important routine with good documentation details already
> > there, though internal to governors and so I would rather keep it.
> 
> It maybe documented, but it isn't kerneldoc, for 2 reasons; a) it
> doesn't meet the standards required qualify as kerneldoc i.e. it's
> missing descriptions for each of the function parameters, which is why
> the kerneldoc checker is complaining about it

Right, so this is a mistake and not intentional probably.

> and b) it is not
> referenced by any *.rst file:
> 
>  git grep kernel-doc::.*cpufreq_governor.c
>  /* no results */

I believed (and it may be wrong) that there are two categories of
routines/structures which can be put in kernel documentation, the
exported ones and the internal ones which are important and are very
useful in understanding the algorithms/logic in the drivers.

I did try to go and look into Documentation/doc-guide/ but couldn't
find any details on this.

You said that it needs to be referenced from some *.rst file, but why
is that necessary ? What if people don't add any documentation in
Documentation/ for their framework or driver but still want stuff to
appear in kernel-doc as they can keep the documentation in comments
more up to date.

-- 
viresh