Re: Kernel docs: muddying the waters a bit

From: Jonathan Corbet
Date: Wed May 04 2016 - 11:09:16 EST


On Wed, 04 May 2016 16:41:50 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> wrote:

> On Wed, 04 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> 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