On Sun, Feb 04, 2024 at 11:39:33AM +0100, Mike Rapoport wrote:

On Mon, Jan 29, 2024 at 04:32:03AM +0000, Matthew Wilcox wrote:

quoted

Our documentation of the current page flags is ... not great.  I think
I can improve it for the page cache side of things; I understand the
meanings of locked, writeback, uptodate, dirty, head, waiters, slab,
mlocked, mappedtodisk, error, hwpoison, readahead, anon_exclusive,
has_hwpoisoned, hugetlb and large_remappable.

Where I'm a lot more shaky is the meaning of the more "real MM" flags,
like active, referenced, lru, workingset, reserved, reclaim, swapbacked,
unevictable, young, idle, swapcache, isolated, and reported.

Perhaps we could have an MM session where we try to explain slowly and
carefully to each other what all these flags actually mean, talk about
what combinations of them make sense, how we might eliminate some of
them to make more space in the flags word, and what all this looks like
in a memdesc world.

And maybe we can get some documentation written about it!  Not trying
to nerd snipe Jon into attending this session, but if he did ...

I suspect Jon will be there anyway, but not sure he'd be willing to do the
writing :)

I was going to propose the "mm docs" session again, but this one seems more
useful than talking yet again about how hard it is to get MM documentation
done.

I'm doing my best to write documentation as I go.  I think we're a bit
better off than we were last year.  Do we have scripts to tell us which
public functions (ie EXPORT_SYMBOL and static inline functions in header
files) have kernel-doc?  And could we run them against kernels from, say,
April 2023, 2022, 2021, 2020, 2019 (and in two months against April 2024)
and see how we're doing in terms of percentage undocumented functions?

There's also the problem of getting long-form documentation done.
But I think that's a different problem from getting kernel-doc written.
Looking at the 55 commits in the last year to Documentation/mm, we seems
to be doing a pretty good job of keeping the documentation we have up
to date.  Just not a great job of adding new documentation.