linux-kernel - Re: [PATCH 00/10] Documentation/Sphinx

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: <87k2i5867p.fsf@intel.com>
Date:	Sat, 04 Jun 2016 15:54:34 +0300
From:	Jani Nikula <jani.nikula@...el.com>
To:	Jonathan Corbet <corbet@....net>
Cc:	Markus Heiser <markus.heiser@...marit.de>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Grant Likely <grant.likely@...retlab.ca>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Dan Allen <dan@...ndevise.io>,
	Russel Winder <russel@...der.org.uk>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Hans Verkuil <hverkuil@...all.nl>
Subject: Re: [PATCH 00/10] Documentation/Sphinx

On Fri, 03 Jun 2016, Jonathan Corbet <corbet@....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@...el.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