Re: [Ksummit-discuss] [TECH TOPIC] Documentation

On Tue, Jun 09, 2020 at 02:53:53PM -0600, Jonathan Corbet wrote:
> The long process of converting the kernel's documentation into RST is
> finally coming to an end...what has that bought us?  We have gone from a
> chaotic pile of incomplete, crufty, and un-integrated docs to a slightly
> better organized pile of incomplete, crufty, slightly better integrated
> docs.  Plus we have the infrastructure to make something better from here.
> 
> What are the next steps for kernel documentation?  What would we really
> like our docs to look like, and how might we find the resources to get
> them to that point?  What sorts of improvements to the build
> infrastructure would be useful?  I'll come with some ideas (some of which
> you've certainly heard before) but will be more interested in listening.

The truth is that I only ever read the documentation in front of the
function implementations.  And LDD.  ;)

There are some subsystems which document their functions in the
Documentation directory.  For example, pm_request_resume() is documented
in Documentation/power/runtime_pm.rst where it describes why it might
return 1 on success.  It would be awesome if we had an automated way to
find this.

I wish that there were a replacement for cscope which showed results in
a sorted order:

Global Implementation
Documentation
Local Implemenatations
(For me the struct device is my 995th result...  Cscope is terrible.
But it's what I use as my default search in the kernel source.  I just
would like to have one search for everything that would find
documentation as well).

regards,
dan carpenter



_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss