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

[Viresh Kumar <viresh.kumar@linaro.org>]

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