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@xxxxxxx +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
