Re: [TECH TOPIC] What kernel documentation could be

[Steven Rostedt <rostedt@goodmis.org>]

On Fri, 17 Jun 2022 14:57:10 -0600
Jonathan Corbet <corbet@lwn.net> 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?

-- Steve


> 
>  - 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
> 
> jon