Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags

[Matthew Wilcox <willy@infradead.org>]

On Tue, Feb 20, 2024 at 09:45:36AM +1100, NeilBrown wrote:
> On Tue, 20 Feb 2024, Matthew Wilcox wrote:
> > The example is filemap_range_has_writeback().  It's EXPORT_SYMBOL_GPL()
> > and it's a helper function for filemap_range_needs_writeback().
> > filemap_range_needs_writeback() has kernel-doc, but nobody should be
> > calling filemap_range_has_writeback() directly, so it shouldn't even
> > exist in the htmldocs.  But we should have a comment on it saying
> > "Use filemap_range_needs_writeback(), don't use this", in case anyone
> > discovers it.  And the existance of that comment should be enough to
> > tell our tools to not flag this as a function that needs kernel-doc.
> > 
> 
> Don't we use a __prefix for internal stuff that shouldn't be used?

No?  Or if we do, we are inconsistent with that convention.  Let's
consider some examples.

__SetPageReferenced -- non-atomic version of SetPageReferenced.
Akin to __set_bit.

__filemap_fdatawrite_range() -- like filemap_fdatawrite_range but
allows the specification of sync_mode

__page_cache_alloc() -- like page_cache_alloc() but takes the gfp mask
directly instead of inferring it from mapping_gfp_mask()

__folio_lock() -- This does fit the "don't call this pattern"!

__set_page_dirty() -- Like set_page_dirty() but allows warn to be
specified.

__filemap_remove_folio() -- Like filemap_remove_folio() but allows it
to be replaced with a shadow entry.

__readahead_folio() -- Another internal one

I mostly confined myself to pagemap.h for this survey, but if you've
conducted a different survey that shows your assertion is generally true
and I've hit on the exceptions to the rule ... ?