From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Markus Heiser <markus.heiser@darmarit.de>,
Jani Nikula <jani.nikula@intel.com>,
"linux-kernel@vger.kernel.org List"
<linux-kernel@vger.kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
linux-doc@vger.kernel.org, Sebastian Reichel <sre@kernel.org>
Subject: Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book
Date: Fri, 26 Aug 2016 06:59:20 -0300 [thread overview]
Message-ID: <20160826065920.0072c88f@vento.lan> (raw)
In-Reply-To: <0464D1F0-1721-4AC2-A7E7-DACDF004F4B9@darmarit.de>
Em Fri, 26 Aug 2016 11:34:38 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:
> Am 23.08.2016 um 16:43 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>
> > Em Mon, 22 Aug 2016 14:57:40 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> >> This short series convers device-drivers.tmpl into the RST format, splits
> >> it up, and sets up the result under Documentation/driver-api/. For added
> >> fun, I've taken one top-level file (hsi.txt) and folded it into the
> >> document as a way of showing the direction I'm thinking I would like things
> >> to go. There is plenty more of this sort of work that could be done, to
> >> say the least - this is just a beginning!
> >>
> >> The formatted results can be seen at:
> >>
> >> http://static.lwn.net/kerneldoc/driver-api/index.html
> >
> > Thanks for doing that! IMHO, the conversion of this book is indeed
> > one of the first things to be done.
>
> >> As part of the long-term task to turn Documentation/ into less of a horror
> >> movie, I'd like to collect documentation of the driver-specific API here.
>
> Hi,
>
> here are my 2cent, about the *generic* content from the kernel-doc
> directive:
>
> .. kernel-doc:: kernel/sched/core.c
> :export:
>
> IMHO directives like the one above are to *generic*. If I read this directive
> I would expect, that all exported symbols are documented. But this is a false
> estimation!
>
> In my POC I use a more restrictive kernel-doc parser
> (https://github.com/return42/linuxdoc). For the directive above the parser
> logs, that some of the exported symbols are not found / not documented:
>
> $ kernel-doc --quiet --list-exports kernel/sched/core.c
> [exported undocumented ] set_cpus_allowed_ptr
> [exported undocumented ] kick_process
> [exported function ] wake_up_process
> [exported undocumented ] preempt_notifier_inc
> [exported undocumented ] preempt_notifier_dec
> [exported function ] preempt_notifier_register
> [exported function ] preempt_notifier_unregister
> [exported undocumented ] single_task_running
> [exported undocumented ] preempt_count_add
> [exported undocumented ] preempt_count_sub
> [exported undocumented ] schedule
> [exported undocumented ] preempt_schedule
> [exported function ] preempt_schedule_notrace
> [exported undocumented ] default_wake_function
> [exported undocumented ] set_user_nice
> [exported function ] sched_setscheduler
> [exported undocumented ] sched_setattr
> [exported function ] sched_setscheduler_nocheck
> [exported undocumented ] _cond_resched
> [exported undocumented ] __cond_resched_lock
> [exported undocumented ] __cond_resched_softirq
> [exported function ] yield
> [exported function ] yield_to
> [exported undocumented ] io_schedule_timeout
> [exported undocumented ] __might_sleep
> [exported undocumented ] ___might_sleep
>
>
> The driver-api is full of *generic* content and IMHO it is not really clear
> what would be a part of the resulting documentation. To illustrate, you
> can take a look on the (old) *automatic* conversion of mine at:
>
> http://return42.github.io/sphkerneldoc/books/device-drivers/index.html
>
> There you see a list of 'Oops: Document generation inconsistency.'
> This kind of missing documentation grows up with changes to
> the source files while there are no errors reported.
>
> What I mean: in most use cases it is better to be explicit and name the
> functions, structs or whatever which should be a part of the documentation.
> e.g.::
>
> .. kernel-doc:: kernel/sched/core.c
> :functions: wake_up_process yield ...
>
> By being explicit, the kernel-doc parser has a chance to identify requested
> but missing documentation and log related error messages.
>
> Summarized:
>
> - *explicit* is better than implicit.
> - the *generic* part of kernel-doc parser should more restrictive
>
> These are my thoughts, even if we do nothing to handle it, we
> should aware about this.
I actually prefer the opposite:
- on a *.c file, it should assume that *all* exported symbols should be
documented (either at the C code itself or at a header file);
- on a *.h file, it should assume that *all* structs, enums, typedefs,
function prototypes and static inline functions should be documented.
As I stated before, we should also add a way to document defines.
Assuming that we add such way, for defines, it should implicitly
ignore the ones used inside the header to enable/disable part of
its contents, like:
#define _FOO_H_
#ifndef _FOO_H_
....
#endif
Then, add an option to allow explicitly ignoring symbols. The lack
of documentation for a symbol that matches the above criteria and
isn't explicitly ignored should be warned, as this is a documentation
gap that should be fixed.
Thanks,
Mauro
next prev parent reply other threads:[~2016-08-26 10:00 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-08-22 20:57 [PATCH 0/3] RFC: The beginning of a proper driver-api book Jonathan Corbet
2016-08-22 20:57 ` [PATCH 1/3] Docs: sphinxify device-drivers.tmpl Jonathan Corbet
2016-08-22 20:57 ` [PATCH 2/3] docs: split up the driver book Jonathan Corbet
2016-08-23 14:30 ` Mauro Carvalho Chehab
2016-08-24 22:46 ` Jonathan Corbet
2016-08-25 1:55 ` Mauro Carvalho Chehab
2016-08-25 20:09 ` Jonathan Corbet
2016-08-22 20:57 ` [PATCH 3/3] docs: Pull HSI documentation together Jonathan Corbet
2016-08-23 0:20 ` Sebastian Reichel
2016-09-06 15:12 ` Jonathan Corbet
2016-08-23 14:43 ` [PATCH 0/3] RFC: The beginning of a proper driver-api book Mauro Carvalho Chehab
2016-08-26 9:34 ` Markus Heiser
2016-08-26 9:59 ` Mauro Carvalho Chehab [this message]
2016-08-26 10:19 ` Jani Nikula
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=20160826065920.0072c88f@vento.lan \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=jani.nikula@intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=markus.heiser@darmarit.de \
--cc=sre@kernel.org \
/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).