From: Matthew Wilcox <willy@infradead.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-kernel@vger.kernel.org,
Andrew Morton <akpm@linux-foundation.org>,
linux-mm@kvack.org
Subject: Re: [PATCH] mm: eliminate "expecting prototype" kernel-doc warnings
Date: Sun, 11 Apr 2021 19:35:45 +0100 [thread overview]
Message-ID: <20210411183545.GD2531743@casper.infradead.org> (raw)
In-Reply-To: <20210411174321.7013-1-rdunlap@infradead.org>
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?
next prev parent reply other threads:[~2021-04-11 18:39 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-11 17:43 [PATCH] mm: eliminate "expecting prototype" kernel-doc warnings Randy Dunlap
2021-04-11 18:35 ` Matthew Wilcox [this message]
2021-04-11 21:01 ` Randy Dunlap
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210411183545.GD2531743@casper.infradead.org \
--to=willy@infradead.org \
--cc=akpm@linux-foundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).