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