lkml.org 
[lkml]   [2016]   [May]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Kernel docs: muddying the waters a bit
On Wed, 04 May 2016 16:41:50 +0300
Jani Nikula <jani.nikula@intel.com> wrote:

> On Wed, 04 May 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> > In reST the directive might look like:
> >
> > <reST-SNIP> -----
> > Device Instance and Driver Handling
> > ===================================
> >
> > .. kernel-doc:: drivers/gpu/drm/drm_drv.c
> > :doc: driver instance overview
> > :exported:
> >
> > <reST-SNAP> -----
>
> Yes, I think something like this, parsed by sphinx directly (via some
> extension perhaps), should be the end goal. I am not sure if it should
> be the immediate first goal though or whether we should reuse the
> existing docproc for now.

I think all of this makes sense. It would be really nice to have the
directives in the native sphinx language like that. I *don't* think we
need to aim for that at the outset; the docproc approach works until we can
properly get rid of it. What would be *really* nice would be to get
support for the kernel-doc directive into the sphinx upstream.

> > <reST-comment-SNAP> --------------
> >
> > Comments with the ":reST:" tag could be exported and pass-through
> > to sphinx.
>
> Disagreed on most of the above.

Agreed with the disagreement here. We can't be adding ":reST:" tags to
comments; I anticipate a wee bit of pushback if we try. It needs to work
with the comments as they are now. It seems that should be possible.

Thanks,

jon

\
 
 \ /
  Last update: 2016-05-04 17:41    [W:0.631 / U:0.128 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site