On Tue, 20 Feb 2024, 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. > Don't we use a __prefix for internal stuff that shouldn't be used? NeilBrown
