On Tue, Feb 20, 2024 at 09:45:36AM +1100, NeilBrown wrote:

On Tue, 20 Feb 2024, Matthew Wilcox wrote:

quoted

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 ... ?