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
