lkml.org 
[lkml]   [2020]   [Jul]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [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

    \
     
     \ /
      Last update: 2020-07-15 09:09    [W:3.960 / U:2.524 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site