Re: [PATCH 00/10] Documentation/Sphinx

[Jani Nikula <jani.nikula@intel.com>]

On Fri, 03 Jun 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> [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@intel.com> 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.

Actually, mostly this is not a problem due to EXPORT_SYMBOL placement,
but rather due to kernel-doc comments being placed in header files above
function declarations while EXPORT_SYMBOL is where it should be next to
the function definition.

I don't think we can force people to move the kernel-doc comments for
exported functions from header files next to the function definitions.

The straightforward fix to this is to add an optional filename parameter
to the kernel-doc extension :export: argument, to pass additional files
to kernel-doc where to look for the EXPORT_SYMBOLs. For example:

.. kernel-doc:: include/drm/foo.h
   :export: drivers/gpu/drm/foo/foo.c drivers/gpu/drm/foo/bar.c

This would instruct kernel-doc to extract documentation from
include/drm/foo.h for all functions that have been exported using
EXPORT_SYMBOL (or _GPL) in include/drm/foo.h, drivers/gpu/drm/foo/foo.c,
or drivers/gpu/drm/foo/bar.c.

We have something along these lines in docproc already with the !D
directive, so nothing altogether surprising.

If my quick grep-fu serves me right, there are about a thousand exported
symbols with kernel-doc comments in the headers. It's a ballpark
figure. They come in batches; a small fraction of that many filenames in
a fraction of the :export: statements would cover most of them.

Before this fix, the workaround is to name the functions with
:functions: argument instead of using :export:.

I'm hoping this is not a blocker for merging the series. If the proposed
fix is acceptable, I'll get it done before v4.8.

BR,
Jani.


The ugly greps:

$ git grep "^EXPORT_SYMBOL" | sed 's/^[^(]*(\([a-zA-Z0-9_]*\)).*/\1/' | sort > exports
$ git grep -h -A1 "^/\*\*$" -- *.h | grep -v "^\(/\*\*\|--\)" | sed 's/^ \*[         ]*\([a-zA-Z0-9_][a-zA-Z0-9_]*\).*/\1/;' | sort > comments
$ comm -1 -2 comments exports | wc -l
952




-- 
Jani Nikula, Intel Open Source Technology Center