Re: [LSF/MM/BPF TOPIC]: MM documentation

[John Hubbard <jhubbard@nvidia.com>]

On 2/6/20 8:53 AM, Mike Rapoport wrote:
> The mm documentation is, well, not entirely up to date. We can opt for
> dropping the outdated parts, which would generate a nice negative
> diffstat, but identifying the outdated documentation requires nearly
> as much effort as updating it, so I think that making and keeping
> the docs up to date would be a better option.
> 
> I'd like to discuss what can be done process-wise to improve the
> situation.
> 
> Some points I had in mind:
> 
> * Pay more attention to docs during review
> * Set an expectation level for docs accompanying a changeset
> * Spend some cycles to review and update the existing docs
> * Spend some more cycles to add new documentation
> 
> I'd appreciate a discussion about how we can get to the second edition
> of "Understanding the Linux Virtual Memory Manager", what are the gaps
> (although they are too many), and what would be the best way to close
> these gaps.
> 

It's a good topic to have.

You know, I've noticed something interesting about the documentation: the
*.rst documents tend to provide critical insight (even if they're imperfect
for various reaons), and furthermore, the generated HTML from the .rst docs
is very nicely readable (visually) as well.

The kerneldoc documentation is different: it's also got absolutely critical
content, and the native source (in .c/.h files) is also very readable. 
However, the generated HTML is *significantly* less readable than any of the
other 3 items I've listed here. That's mainly because the system picks up 
all kerneldoc items, even the short and less informative ones.

Yes, we can keep trying to make the kerneldoc documentation cleaner. But
it's also reasonable to claim that their are "tiers" of quality, and it's
OK for kerneldoc comments to be at a lower tier than the nice .rst docs.
In fact, we sort of implicitly do so. 

When browsing at the HTML level, I wish there were maybe some slight visual
indicator of these tiers. Because honestly, it seems reasonable for kernel
developers to do something like this:

* If reading at the HTML level, read the "docs" (.rst --> .html docs).

* Once the docs move to the kerneldoc level, you really want the source code
right next to the (often cryptic) kerneldoc documentation. So at that point,
I want out of the HTML, but the HTMl docs are all intermingled.


Maybe it's wrong to want this, but I'm gonna say it anyway. :) 


thanks,
-- 
John Hubbard
NVIDIA