| Message ID | 20210411174321.7013-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | mm: eliminate "expecting prototype" kernel-doc warnings | expand |
On Sun, Apr 11, 2021 at 10:43:21AM -0700, Randy Dunlap wrote: > +++ linux-next-20210409/mm/mmu_gather.c > @@ -250,7 +250,7 @@ void tlb_flush_mmu(struct mmu_gather *tl > } > > /** > - * tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down > + * __tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down > * @tlb: the mmu_gather structure to initialize > * @mm: the mm_struct of the target address space > * @fullmm: @mm is without users and we're going to destroy the full address I think this is the wrong fix. __tlb_gather_mmu is static, so documenting it isn't going to do much good. Instead, this doc should be moved down to tlb_gather_mmu(). For bonus points, add documentation for tlb_gather_mmu_fullmm(). > --- linux-next-20210409.orig/mm/oom_kill.c > +++ linux-next-20210409/mm/oom_kill.c > @@ -171,10 +171,11 @@ static bool oom_unkillable_task(struct t > } > > /** > - * Check whether unreclaimable slab amount is greater than > - * all user memory(LRU pages). > + * should_dump_unreclaim_slab - Check whether unreclaimable slab amount > + * is greater than all user memory (LRU pages). > + * > * dump_unreclaimable_slab() could help in the case that > - * oom due to too much unreclaimable slab used by kernel. > + * oom is due to too much unreclaimable slab used by kernel. > */ > static bool should_dump_unreclaim_slab(void) This is static. I'd just remove the second '*' and turn it into a non-kernel-doc comment. > { > --- linux-next-20210409.orig/mm/shuffle.c > +++ linux-next-20210409/mm/shuffle.c > @@ -148,7 +148,7 @@ void __meminit __shuffle_zone(struct zon > } > > /** > - * shuffle_free_memory - reduce the predictability of the page allocator > + * __shuffle_free_memory - reduce the predictability of the page allocator > * @pgdat: node page data > */ > void __meminit __shuffle_free_memory(pg_data_t *pgdat) Nobody calls __shuffle_free_memory() directly. If anything, the doc should be moved to shuffle_free_memory(). But since it has precisely one caller, and it's within mm/, I'm more inclined to leave this comment where it is and turn it into a non-kernel-doc comment. Thoughts?
On 4/11/21 11:35 AM, Matthew Wilcox wrote: > On Sun, Apr 11, 2021 at 10:43:21AM -0700, Randy Dunlap wrote: >> +++ linux-next-20210409/mm/mmu_gather.c >> @@ -250,7 +250,7 @@ void tlb_flush_mmu(struct mmu_gather *tl >> } >> >> /** >> - * tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down >> + * __tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down >> * @tlb: the mmu_gather structure to initialize >> * @mm: the mm_struct of the target address space >> * @fullmm: @mm is without users and we're going to destroy the full address > > I think this is the wrong fix. __tlb_gather_mmu is static, so documenting > it isn't going to do much good. Instead, this doc should be moved > down to tlb_gather_mmu(). For bonus points, add documentation for > tlb_gather_mmu_fullmm(). I'll certainly add the doc for tlb_gather_mmu_fullmm() -- don't want to lose that @fullmm: comment. > >> --- linux-next-20210409.orig/mm/oom_kill.c >> +++ linux-next-20210409/mm/oom_kill.c >> @@ -171,10 +171,11 @@ static bool oom_unkillable_task(struct t >> } >> >> /** >> - * Check whether unreclaimable slab amount is greater than >> - * all user memory(LRU pages). >> + * should_dump_unreclaim_slab - Check whether unreclaimable slab amount >> + * is greater than all user memory (LRU pages). >> + * >> * dump_unreclaimable_slab() could help in the case that >> - * oom due to too much unreclaimable slab used by kernel. >> + * oom is due to too much unreclaimable slab used by kernel. >> */ >> static bool should_dump_unreclaim_slab(void) > > This is static. I'd just remove the second '*' and turn it into a > non-kernel-doc comment. Done. >> { >> --- linux-next-20210409.orig/mm/shuffle.c >> +++ linux-next-20210409/mm/shuffle.c >> @@ -148,7 +148,7 @@ void __meminit __shuffle_zone(struct zon >> } >> >> /** >> - * shuffle_free_memory - reduce the predictability of the page allocator >> + * __shuffle_free_memory - reduce the predictability of the page allocator >> * @pgdat: node page data >> */ >> void __meminit __shuffle_free_memory(pg_data_t *pgdat) > > Nobody calls __shuffle_free_memory() directly. If anything, the doc > should be moved to shuffle_free_memory(). But since it has precisely > one caller, and it's within mm/, I'm more inclined to leave this comment > where it is and turn it into a non-kernel-doc comment. Thoughts? > Sounds good. Thanks. v2 coming soon.
--- linux-next-20210409.orig/mm/mmu_gather.c +++ linux-next-20210409/mm/mmu_gather.c @@ -250,7 +250,7 @@ void tlb_flush_mmu(struct mmu_gather *tl } /** - * tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down + * __tlb_gather_mmu - initialize an mmu_gather structure for page-table tear-down * @tlb: the mmu_gather structure to initialize * @mm: the mm_struct of the target address space * @fullmm: @mm is without users and we're going to destroy the full address --- linux-next-20210409.orig/mm/oom_kill.c +++ linux-next-20210409/mm/oom_kill.c @@ -171,10 +171,11 @@ static bool oom_unkillable_task(struct t } /** - * Check whether unreclaimable slab amount is greater than - * all user memory(LRU pages). + * should_dump_unreclaim_slab - Check whether unreclaimable slab amount + * is greater than all user memory (LRU pages). + * * dump_unreclaimable_slab() could help in the case that - * oom due to too much unreclaimable slab used by kernel. + * oom is due to too much unreclaimable slab used by kernel. */ static bool should_dump_unreclaim_slab(void) { --- linux-next-20210409.orig/mm/shuffle.c +++ linux-next-20210409/mm/shuffle.c @@ -148,7 +148,7 @@ void __meminit __shuffle_zone(struct zon } /** - * shuffle_free_memory - reduce the predictability of the page allocator + * __shuffle_free_memory - reduce the predictability of the page allocator * @pgdat: node page data */ void __meminit __shuffle_free_memory(pg_data_t *pgdat)
Fix stray kernel-doc warnings in mm/ due to mis-typed or missing function names. Quietens these kernel-doc warnings: ../mm/mmu_gather.c:264: warning: expecting prototype for tlb_gather_mmu(). Prototype was for __tlb_gather_mmu() instead ../mm/oom_kill.c:180: warning: expecting prototype for Check whether unreclaimable slab amount is greater than(). Prototype was for should_dump_unreclaim_slab() instead ../mm/shuffle.c:155: warning: expecting prototype for shuffle_free_memory(). Prototype was for __shuffle_free_memory() instead Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: linux-mm@kvack.org --- mm/mmu_gather.c | 2 +- mm/oom_kill.c | 7 ++++--- mm/shuffle.c | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-)