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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <BY2PR21MB0036BE25DDC135E89A357C75CB750@BY2PR21MB0036.namprd21.prod.outlook.com>
Date:   Tue, 24 Jan 2017 15:35:50 +0000
From:   Matthew Wilcox <mawilcox@...rosoft.com>
To:     Markus Heiser <markus.heiser@...marit.de>,
        Jonathan Corbet <corbet@....net>
CC:     "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>
Subject: RE: [PATCH] kernel-doc: Handle returning pointers to pointers

From: Markus Heiser [mailto:markus.heiser@...marit.de]
> Am 23.01.2017 um 16:24 schrieb Jonathan Corbet <corbet@....net>:
> > 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< ---

Locking
-------

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

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