On Tue, 20 Feb 2024, Matthew Wilcox wrote: > 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 ... ? > Yes, __ is used for other things too. It would be nice to have some consistency with naming, but probably impossible. And with 1074 functions named __foo having kernel doc already, it is too late to close that gate. :-( Thanks, NeilBrown
