From: Viresh Kumar <viresh.kumar@linaro.org>
To: Lee Jones <lee.jones@linaro.org>
Cc: rjw@rjwysocki.net, linux-arm-kernel@lists.infradead.org,
linux-kernel@vger.kernel.org, linux-pm@vger.kernel.org,
Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>,
Jun Nakajima <jun.nakajima@intel.com>,
Alexander Clouter <alex@digriz.org.uk>
Subject: Re: [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling_rate() header to standard comment block
Date: Wed, 15 Jul 2020 13:32:36 +0530 [thread overview]
Message-ID: <20200715080236.n3gecwhidorn4rqq@vireshk-i7> (raw)
In-Reply-To: <20200715073150.GX1398296@dell>
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. But the layout
of things wont' be very nice right now.
--
viresh
next prev parent reply other threads:[~2020-07-15 8:02 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-07-14 14:50 [PATCH 00/13] Rid W=1 warnings in CPUFreq Lee Jones
2020-07-14 14:50 ` [PATCH 01/13] cpufreq: freq_table: Demote obvious misuse of kerneldoc to standard comment blocks Lee Jones
2020-07-15 2:44 ` Viresh Kumar
2020-07-14 14:50 ` [PATCH 02/13] cpufreq: cpufreq: Demote lots of function headers unworthy of kerneldoc status Lee Jones
2020-07-15 2:49 ` Viresh Kumar
2020-07-15 6:47 ` Lee Jones
2020-07-15 7:09 ` Viresh Kumar
2020-07-14 14:50 ` [PATCH 03/13] cpufreq: cpufreq_governor: Demote store_sampling_rate() header to standard comment block Lee Jones
2020-07-15 2:52 ` Viresh Kumar
2020-07-15 6:45 ` Lee Jones
2020-07-15 7:08 ` Viresh Kumar
2020-07-15 7:31 ` Lee Jones
2020-07-15 8:02 ` Viresh Kumar [this message]
2020-07-15 8:15 ` Lee Jones
2020-07-14 14:50 ` [PATCH 04/13] cpufreq: sti-cpufreq: Fix some formatting and misspelling issues Lee Jones
2020-07-15 2:58 ` Viresh Kumar
2020-07-14 14:50 ` [PATCH 05/13] cpufreq/arch: powerpc: pasemi: Move prototypes to shared header Lee Jones
2020-07-15 3:07 ` Viresh Kumar
2020-07-15 3:49 ` Olof Johansson
2020-07-15 3:51 ` Viresh Kumar
2020-07-15 6:36 ` Lee Jones
2020-07-15 6:39 ` Viresh Kumar
2020-07-15 3:26 ` Olof Johansson
2020-07-15 6:33 ` Lee Jones
2020-07-15 6:46 ` Olof Johansson
2020-07-15 7:33 ` Lee Jones
2020-07-14 14:50 ` [PATCH 06/13] cpufreq: powernv-cpufreq: Functions only used in call-backs should be static Lee Jones
2020-07-15 3:07 ` Viresh Kumar
2020-07-14 14:50 ` [PATCH 07/13] cpufreq: powernv-cpufreq: Fix a bunch of kerneldoc related issues Lee Jones
2020-07-15 3:09 ` Viresh Kumar
2020-07-14 14:50 ` [PATCH 08/13] cpufreq: acpi-cpufreq: Take 'dummy' principle one stage further Lee Jones
2020-07-14 16:03 ` Rafael J. Wysocki
2020-07-14 16:20 ` Robin Murphy
2020-07-14 21:00 ` Lee Jones
2020-07-14 14:50 ` [PATCH 09/13] cpufreq: acpi-cpufreq: Remove unused ID structs Lee Jones
2020-07-14 15:58 ` Rafael J. Wysocki
2020-07-14 21:03 ` Lee Jones
2020-07-15 3:24 ` Viresh Kumar
2020-07-15 3:27 ` Viresh Kumar
2020-07-15 6:37 ` Lee Jones
2020-07-15 11:27 ` Rafael J. Wysocki
2020-07-15 11:34 ` Lee Jones
2020-07-15 11:44 ` Rafael J. Wysocki
2020-07-15 11:50 ` Lee Jones
2020-07-15 12:07 ` Lee Jones
2020-07-15 12:11 ` Rafael J. Wysocki
2020-07-15 12:09 ` Rafael J. Wysocki
2020-07-15 12:16 ` Lee Jones
2020-07-15 12:30 ` Robin Murphy
2020-07-15 12:38 ` Lee Jones
2020-07-14 14:50 ` [PATCH 10/13] cpufreq: powernow-k8: Make use of known set but not used variables Lee Jones
2020-07-14 17:43 ` Rafael J. Wysocki
2020-07-14 21:01 ` Lee Jones
2020-07-14 14:50 ` [PATCH 11/13] cpufreq: pcc-cpufreq: Remove unused ID structs Lee Jones
2020-07-14 17:42 ` Rafael J. Wysocki
2020-07-14 14:50 ` [PATCH 12/13] cpufreq: intel_pstate: Supply struct attribute description for get_aperf_mperf_shift() Lee Jones
2020-07-14 16:35 ` Rafael J. Wysocki
2020-07-14 21:03 ` Lee Jones
2020-07-15 12:38 ` Rafael J. Wysocki
2020-07-14 14:50 ` [PATCH 13/13] cpufreq: amd_freq_sensitivity: Remove unused ID structs Lee Jones
2020-07-14 17:15 ` Kim Phillips
2020-07-14 21:02 ` Lee Jones
2020-07-14 21:13 ` Kim Phillips
2020-07-15 6:47 ` Lee Jones
2020-07-15 3:36 ` [PATCH 00/13] Rid W=1 warnings in CPUFreq Viresh Kumar
2020-07-15 6:32 ` Lee Jones
2020-07-15 6:38 ` Viresh Kumar
2020-07-15 7:34 ` Lee Jones
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200715080236.n3gecwhidorn4rqq@vireshk-i7 \
--to=viresh.kumar@linaro.org \
--cc=alex@digriz.org.uk \
--cc=jun.nakajima@intel.com \
--cc=lee.jones@linaro.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-pm@vger.kernel.org \
--cc=rjw@rjwysocki.net \
--cc=venkatesh.pallipadi@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).