Re: [PATCH] kernel-doc: Handle returning pointers to pointers

[Markus Heiser]

Am 23.01.2017 um 09:18 schrieb Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>:

> Clearly nobody ever tried to build the documentation for the radix tree
> before:
> 
> include/linux/radix-tree.h:400: warning: cannot understand function
> prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter,
> unsigned long start) '
> 
> Indeed, the regexes only handled a single '*', not one-or-more.

Hi Matthew !

short answer: Thanks a lot
    Acked-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>

to be more verbose:
   what I have tested and what I recommend  ...

I maintain my own stack of "linuxdoc" with a python version
of the kernel-doc script (hosted on github). It uses the same
regexes as the perl version (using a python rewrite here has some
other benefits, one you will see below). I merged your patch:

  https://github.com/return42/linuxdoc/commit/6c1b85b

> I have tried to fix that, but now I have perl regexes all over my hands, and
> I fear I shall never be clean again.


Another part of my stack is the 'sphkerneldoc' repository
with reST, generated from whole kernel source tree. Here is
the diff of what your patch produce on the whole source tree:  

  https://github.com/return42/sphkerneldoc/commit/e64c19822

So I we see, everything is fine with your patch (no reason to
fear any regression).

And to complete the roundtrip, here is the HTML rendered radix-tree.h

  https://h2626237.stratoserver.net/kernel/linux_src_doc/include/linux/radix-tree_h.html
  
with the new 'radix_tree_iter_init', 'radix_tree_next_chunk' etc. in.

BTW: the kernel-doc python variant does some *linting*, here is what
it says:

$ kernel-lintdoc include/linux/radix-tree.h
...
/share/linux-docs-next/include/linux/radix-tree.h:218: :ERROR: odd construct, gathering documentation of a function outside of the main block?!?
/share/linux-docs-next/include/linux/radix-tree.h:219: :ERROR: Comment without header was found split-state --> 4
/share/linux-docs-next/include/linux/radix-tree.h:219: :WARN: Incorrect use of kernel-doc format:  * radix_tree_deref_slot        - dereference a slot
/share/linux-docs-next/include/linux/radix-tree.h:167: :WARN: no description found for parameter 'pslot'
/share/linux-docs-next/include/linux/radix-tree.h:167: :WARN: function name from comment differs:  Radix <--> radix_tree_deref_slot
/share/linux-docs-next/include/linux/radix-tree.h:167: :WARN: no description found for return-value of function 'radix_tree_deref_slot()'
/share/linux-docs-next/include/linux/radix-tree.h:237: :WARN: no description found for parameter 'treelock'
/share/linux-docs-next/include/linux/radix-tree.h:398: :WARN: no description found for return-value of function 'radix_tree_iter_retry()'
/share/linux-docs-next/include/linux/radix-tree.h:571: :WARN: total errors: 2 / total warnings: 6

Don't look to close at all these warnings and errors since they are
consecutive faults of the first, a missing 'DOC:' in the *overall*
header file's comment block.

Here is my patch for this. May you like to add this to your patch:  

diff --git a/include/linux/radix-tree.h b/include/linux/radix-tree.h
index 5dea8f6..33cbc1b 100644
--- a/include/linux/radix-tree.h
+++ b/include/linux/radix-tree.h
@@ -164,7 +164,7 @@ static inline unsigned int iter_shift(const struct radix_tree_iter *iter)
 }

 /**
- * Radix-tree synchronization
+ * DOC: Radix-tree synchronization
  *
  * The radix-tree API requires that users provide all synchronisation (with
  * specific exceptions, noted below).

with this small patch, we also get header's 'DOC: comment' as HTML.

Unfortunately the comment block of func 'radix_tree_iter' is on top of
the header file. To be perfect, move the 'DOC: comment' block on top of
the header file, so that it is the first comment block (vice versa, move
radix_tree_iter below DOC).
  
Again, thanks a lot.

  -- Markus --

PS: I hope there comes a day we merge the kernel-doc.py into kernel's
source tree, make linting and other stuff available to all developers
and get rid of the complicated steps I needed above. :-o