Re: [TECH TOPIC] What kernel documentation could be

From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
To: Steven Rostedt <rostedt@goodmis.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	ksummit-discuss@lists.linuxfoundation.org,
	ksummit@lists.linux.dev
Subject: Re: [TECH TOPIC] What kernel documentation could be
Date: Sat, 25 Jun 2022 20:48:55 +0300	[thread overview]
Message-ID: <YrdKhw8gww20ODYr@pendragon.ideasonboard.com> (raw)
In-Reply-To: <20220625134328.19b5356c@rorschach.local.home>

Hi Steven,

On Sat, Jun 25, 2022 at 01:43:28PM -0400, Steven Rostedt wrote:
> On Fri, 17 Jun 2022 14:57:10 -0600 Jonathan Corbet wrote:
> 
> > The development community has put a lot of work into the kernel's
> > documentation directory in recent years, with visible results. But the
> > kernel's documentation still falls far short of the standard set by many
> > other projects, and there is a great deal of "tribal knowledge" in our
> > community that is not set down. I'd like to look at the successes and
> > failures of the work so far, but intent to focus on a discussion of what
> > our documentation should be and what we can do to get it there.
> > 
> > Questions to discuss include:
> > 
> >  - Bringing an coherent overall structure to Documentation/
> > 
> >  - Making it easier for developers to improve the documentation.
> 
> Is there a way to mark comments in the code as "design docs". And I
> don't mean the kernel-doc that is already above functions.
> 
> I have lots of comments about the design of complex code just above the
> code it is describing. Which is much more likely to get updated when
> the design changes or gets new features.
> 
> I found my design documents I have under Documentation to become
> grossly obsolete over time, where as the comments above the code I can
> keep up with.
> 
> Is there already some kind of mark up that we can add to the comments to state:
> 
>  ** .design.trace/ftrace.rst .ringbuffer. **
> 
> or something that can be extracted into another document? With the
> above example, I could have in Documentatino/trace/ftrace.rst a
> 
>  .design .ringbuffer.
> 
> And the comment from the code would be extracted into the html
> documents that are created?
> 
> Or maybe it would be better to reference the code from the documentation?
> 
>  .include kerne/trace/ring_buffer.c .ringbuffer.
> 
> That will look for a tag in kernel/trace/ring_buffer.c called
> ".ringbuffer" and pull in the comment into the document under Documentation.
> 
> Thoughts?

See the "DOC: overview" block in drivers/gpu/drm/drm_atomic_helper.c,
and how it is integrated in Documentation/gpu/drm-kms-helpers.rst with

.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
   :doc: overview

Is that what you're looking for ?

> >  - What we would like from Sphinx and what we can do to make it happen
> > 
> >  - Making the docs build system less ugly and more maintainable
> > 
> >  - Integrating rustdoc documentation

-- 
Regards,

Laurent Pinchart