linux-kernel - Re: [PATCH] mm: eliminate "expecting prototype" kernel-doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20210411183545.GD2531743@casper.infradead.org>
Date:   Sun, 11 Apr 2021 19:35:45 +0100
From:   Matthew Wilcox <willy@...radead.org>
To:     Randy Dunlap <rdunlap@...radead.org>
Cc:     linux-kernel@...r.kernel.org,
        Andrew Morton <akpm@...ux-foundation.org>, linux-mm@...ck.org
Subject: Re: [PATCH] mm: eliminate "expecting prototype" kernel-doc warnings

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?