On Tue, Jun 19, 2018 at 07:11:56AM -0700, Matthew Wilcox wrote:
> On Mon, Jun 18, 2018 at 10:10:28AM -0700, Matthew Wilcox wrote:
> > On Mon, Jun 18, 2018 at 04:36:34PM +0300, Mike Rapoport wrote:
> > > Hi,
> > >
> > > These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
> > > from the sphinx generator.
> > >
> > > This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
> > > is used without explicit selection of functions or function types. For
> > > instance, [1] has "IDA description" and "idr synchronization" twice.
> >
> > Hah, I just found an abandoned patch for this in a disused git tree.
> > I was wondering whether I needed to resurrect it. Enthusiastically,
> >
> > Acked-by: Matthew Wilcox <willy@xxxxxxxxxxxxx>
>
> Here's the patch I found (I couldn't refind it at the time):
>
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index d15e07f36881..d86d88da1d75 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -47,6 +47,7 @@ class KernelDocDirective(Directive):
> optional_arguments = 4
> option_spec = {
> 'doc': directives.unchanged_required,
> + 'nodoc': directives.unchanged,
> 'functions': directives.unchanged_required,
> 'export': directives.unchanged,
> 'internal': directives.unchanged,
> @@ -74,6 +75,8 @@ class KernelDocDirective(Directive):
> export_file_patterns = str(self.options.get('internal')).split()
> elif 'doc' in self.options:
> cmd += ['-function', str(self.options.get('doc'))]
> + elif 'nodoc' in self.options:
> + cmd += ['-no-doc-sections']
> elif 'functions' in self.options:
> for f in str(self.options.get('functions')).split():
> cmd += ['-function', f]
>
> I did it while I was trying to create good radix tree documentation,
> which led to me realising that was a Herculean task (specifically: the
> stables).
>
> I ended up doing this instead:
>
> +The Public API
> +==============
> +
> +The public API can be found in ``<linux/radix-tree.h>``. To use a
> +radix tree in your data structure, embed a :c:type:`struct radix_tree_root`
> +in it, and initialise it using ``INIT_RADIX_TREE``. You can also use
> +a file-local or global radix tree by defining a :c:type:`RADIX_TREE` as you
> +would a :c:type:`LIST_HEAD`.
> +
> +.. Not actually "internal", but I need to exclude the 'doc' paragraph, and
> + this is the best way to do it.
> +.. kernel-doc:: include/linux/radix-tree.h
> + :internal:
> +
> +.. kernel-doc:: lib/radix-tree.c
> + :export:
>
> I'm not sure if I agree with me-of-January-2017 that this is the "best"
> way to do it, but maybe that'll point to another way of achieving the
> same thing.
>
Actually, in the IDR case the same trick would work.
In more general case it's even possible to use
.. kernel-doc:: path/to/file.c
:export:
.. kernel-doc: path/to/file.c
:internal:
and get all the functions without the docs sections :)
But IMHO having a directive for this would be nicer. If there are no
objections to Jani's suggestion to use empty :functions: instead of
:nodoc: I'm going to send v2.
--
Sincerely yours,
Mike.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
