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

[Hannes Reinecke <hare@suse.de>]

On 2/19/24 21:13, Matthew Wilcox wrote:
> On Wed, Feb 07, 2024 at 05:51:44PM +0200, Mike Rapoport wrote:
>> On Sun, Feb 04, 2024 at 09:34:01PM +0000, Matthew Wilcox wrote:
>>> 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?
>>
>> We didn't have such script, but it was easy to compare "grep
>> EXPORT_SYMBOL\|static inline" with ".. c:function" in kernel-doc.
>> We do improve slowly, but we are still below 50% with kernel-doc for
>> EXPORT_SYMBOL functions and slightly above 10% for static inlines.
> 
> Thanks for doing this!  Data is good ;-)
> 
> I just came across an interesting example of a function which I believe
> should NOT have kernel-doc.  But it should have documentation for why it
> doesn't have kernel-doc!  Any thoughts about how we might accomplish that?
> 
> 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.
> 
> 
Or, indeed, coming up with a method of signalling "this is an internal
function for a specific need, don't use otherwise".

EXPORT_SYMBOL_INTERNAL?

I would love to have it; it would solve _so_ many problems we're having
wrt kABI...

Cheers,

Hannes
-- 
Dr. Hannes Reinecke                  Kernel Storage Architect
hare@suse.de                                +49 911 74053 688
SUSE Software Solutions GmbH, Frankenstr. 146, 90461 Nürnberg
HRB 36809 (AG Nürnberg), GF: I. Totev, A. McDonald, W. Knoblich