On Mon, Jun 18, 2018 at 10:10:28AM -0700, Matthew Wilcox wrote:

quoted

On Mon, Jun 18, 2018 at 04:36:34PM +0300, Mike Rapoport wrote:

quoted

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@infradead.org>

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.