Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1413443

Re: [PATCH 00/10] Documentation/Sphinx

Show all headers | View raw

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

> 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

Back to linux.kernel | Previous | Next — Next in thread | Find similar | Unroll thread

Thread

Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:20 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:30 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 15:10 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-06-03 22:30 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 15:00 +0200

csiph-web