On Tue, Jan 30, 2018 at 04:28:50PM +0200, Mike Rapoport wrote: > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote: > > 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. We should be really clear what kind of documentation we're trying to create. There are four distinct types of documentation which would be useful: - How, when and why to use the various function calls and their parameters from the perspective of a user outside the mm/ hierarchy. Device driver authors, filesystem authors and others of their ilk. - The overall philosophy and structure of the mm directory, what it does, why it does it, perhaps even outlines of abandoned approaches. - What functionality the mm subsystem requires from others. For example, what does the mm rely on from the CPU architectures (and maybe it would make sense to also include services the mm layer provides to arches in this section, like setting up sparsemem). - How to tweak the various knobs that the mm subsystem provides. Maybe this is all adequately documented elsewhere already. Perhaps others can think of other types of documentation which would be useful. That shouldn't detract from my main point, which is that saying "Now we have mm documentation" is laudable, but not enough. -- 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>
