Re: [LSF/MM TOPIC] mm documentation

[Mike Rapoport <rppt@linux.vnet.ibm.com>]

On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> > (forgot to CC linux-mm)
> > 
> > On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> > > Hello,
> > > 
> > > The mm kernel-doc documentation is not in a great shape. 
> > > 
> > > Some of the existing kernel-doc annotations were not reformatted during
> > > transition from dockbook to sphix. Sometimes the parameter descriptions
> > > do not match actual code. But aside these rather mechanical issues there
> > > are several points it'd like to discuss:
> > > 
> > > * Currently, only 14 files are linked to kernel-api.rst under "Memory
> > > Management in Linux" section. We have more than hundred files only in mm.
> > > Even the existing documentation is not generated when running "make
> > > htmldocs"
> 
> Is this documentation anywhere close to be actually useful?

Some parts are documented better, some worse. For instance, bootmem and
z3fold are covered not bad at all, but, say, huge_memory has no structured
comments at all. Roughly half of the files in mm/ have some documentation,
but I didn't yet read that all to say how much of it is actually useful.

And maybe having some skeleton for MM API in htmldocs with at least some
documentation will encourage people to look at the documentation.

> -- 
> Michal Hocko
> SUSE Labs
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>