On Tue, 2018-01-30 at 16:28 +0200, Mike Rapoport wrote: > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote: > > > > On Tue 30-01-18 14:54:44, Mike Rapoport wrote: > > > > > > 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. > > > > 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. > > API documentations is important for kernel developers who are not > deeply involved with mm. When one develops a device driver, knowing > how to allocate and free memory is essential. And, while *malloc are > included in kernel-api.rst, CMA and HMM documentation is not visible. Documentation is also one way new people get into the project. Not being top priority is fine, but "far from" top priority implies not worth doing, which gives the wrong impression. > > We are seriously lacking any highlevel one which describes the > > design and subsytems interaction. > > I should have describe it better, but by "creating a new structure > for mm documentation" I've also meant adding high level description. > > > > > Well, we have missed that train years ago. It will be really hard > > to catch up. > > At least we can try. How about simply insisting on adequately documenting new stuff and asking submitters to add documentation when they change something. The latter, at least, is fairly essential: there's nothing worse than documentation that's actively wrong. The former is useful to reviewers. I'm not saying this alone will ever get you to 100%, but at least it's an incremental change which isn't too burdensome and which moves the needle in the right direction. James -- To unsubscribe, send a message with 'unsubscribe linux-mm' in the body to majordomo@xxxxxxxxx. For more info on Linux MM, see: http://www.linux-mm.org/ . Don't email: <a href=mailto:"dont@xxxxxxxxx";> email@xxxxxxxxx </a>
