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

[Matthew Wilcox]

From: Markus Heiser [mailto:markus.heiser@xxxxxxxxxxx]
> Am 23.01.2017 um 09:18 schrieb Matthew Wilcox
> <mawilcox@xxxxxxxxxxxxx>:
> Hi Matthew !
> 
> short answer: Thanks a lot
>     Acked-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>

Excellent!

> 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:

Are there plans to merge that?  It feels so odd to have a python script calling a perl script ...

> 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:

Oh, that's funny.  Other places had the same problem ... I guess nobody had tried to fix that warning yet :-)

> 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.

I have that and much, much more in my tree right now ... I wrote a radix-tree.rst on the plane, and I've been tidying up all kinds of problems that sphinx noticed, or just reading the documentation made glaringly obvious.