On Tue, Jan 30, 2018 at 09:32:04AM -0800, Randy Dunlap wrote: > On 01/30/2018 06:28 AM, 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. > > > >> 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. > > Hi, > I would move it all to a new mm.rst file. That would be easier to maintain > and also allow parallel building. Agree. Could also be Documentation/vm/index.rst. > -- > ~Randy > -- Sincerely yours, Mike. -- 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>
