linux-kernel - Re: Kernel docs: muddying the waters a bit

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: <20160504090901.334c2ae7@lwn.net>
Date:	Wed, 4 May 2016 09:09:01 -0600
From:	Jonathan Corbet <corbet@....net>
To:	Jani Nikula <jani.nikula@...el.com>
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>,
	"linux-media\@vger.kernel.org linux-media" 
	<linux-media@...r.kernel.org>,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit

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

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