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

From: Matthew Wilcox
Date: Tue Jan 24 2017 - 10:36:08 EST

From: Markus Heiser [mailto:markus.heiser@xxxxxxxxxxx]
> Am 23.01.2017 um 16:24 schrieb Jonathan Corbet <corbet@xxxxxxx>:
> > Markus, would you consider sending out a new patch set for review?
> Yes, I send RFC soon ...

Could I ask for some features? I'd've been trying to add them to the perl script, but since I am terrible at writing both Perl and Python, and I have your attention right now ...

1. An option to select which functions are output by regular expression. I would like to be able to say:

.. kernel-doc:: lib/radix-tree.c
:functions: radix.*

to avoid the IDA/IDR functions which now live in radix-tree.c from having their kernel-doc output.

2. An option to output everything *except* the /** DOC: */ comments. I want to be able to do something like this in my .rst file:

--- 8< ---


.. kernel-doc:: include/linux/radix-tree.h
:doc: Radix-tree synchronization

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

.. kernel-doc:: include/linux/radix-tree.h

--- >8 ---

3. I think it would also make sense, as well as being able to ask for 'all exported symbols', to be able to ask for 'all non-static symbols'; we want to document __radix_tree_lookup(), but we only want to export it as a symbol if a modular user shows up (this isn't critical for me since I want to filter out the idr/ida functions as well, but it might be useful for other files).