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

[Daniel Vetter <daniel.vetter@ffwll.ch>]

On Wed, Jun 10, 2020 at 10:51 AM Dan Carpenter <dan.carpenter@oracle.com> wrote:
>
> 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.

My recommendation is to move these into the code, as kerneldoc. And
then pull it into the .rst using one of the kerneldoc include
directives.

Large chunks of Documentation/gpu/*.rst files are just scaffolding to
pull the comments out of source files. The only thing we have in .rst
files is the big picture overview stuff - even local overview stuff is
simply done as DOC: kerneldoc comments in source code.
-Daniel


>
> 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
> Ksummit-discuss@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss



--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Ksummit-discuss mailing list
Ksummit-discuss@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss