On Tue 30-01-18 14:54:44, Mike Rapoport wrote:

On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:

quoted

On Tue 30-01-18 12:54:50, Mike Rapoport wrote:

quoted

(forgot to CC linux-mm)

On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:

quoted

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.

It is good to hear that at least something has a documentation coverage.
I was asking mostly because I _think_ that the API documentation is far
from the top priority. We are seriously lacking any highlevel one which
describes the design and subsytems interaction. Well, we have missed
that train years ago. It will be really hard to catch up.

-- 
Michal Hocko
SUSE Labs

--
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>