Re: [PATCH 00/10] Documentation/Sphinx

[Jonathan Corbet]

[So I'm finally trying to get into this for real, hopefully I won't be
interrupted too many times...expect a few mails as I catch up.]

On Fri, 20 May 2016 16:39:31 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> wrote:

> There are a few tradeoffs, of course. First, this requires that the
> EXPORT_SYMBOL markers are placed immediately after the function being
> exported, as kernel-doc will only look at one file at a time. This is
> the recommendation anyway. 

As I understand it, the technical reasons that kept some markers in
separate files should no longer be relevant, so this is probably OK.  It
would be nice to have a sense for how many sites need to be fixed.

> Second, we lose support for the !C docproc directive to check
> that all kernel-doc comments in a file are used. This is probably
> something we'd like to have back in the future, but at this time I think
> it's an acceptable tradeoff wrt the gains.

This is maybe a job for a separate tool.  A related issue is the (fairly
frequent) "oh look, none of the comments in $FILE are being used"
realization that seems to happen fairly often.  It would be nice to check
for that, but that's going to be hard to shoehorn into Sphinx.

jon