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

Dan Carpenter
2020-06-10T08:51:20Z

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