linux-kernel - Re: [PATCH] mm/swap.c: fix kernel-doc functions and parameters

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]

Date:   Sun, 28 Jan 2018 21:15:32 -0800
From:   Matthew Wilcox <willy@...radead.org>
To:     Randy Dunlap <rdunlap@...radead.org>
Cc:     Linux MM <linux-mm@...ck.org>,
        Andrew Morton <akpm@...ux-foundation.org>,
        LKML <linux-kernel@...r.kernel.org>, Jan Kara <jack@...e.cz>
Subject: Re: [PATCH] mm/swap.c: fix kernel-doc functions and parameters

On Sun, Jan 28, 2018 at 08:01:08PM -0800, Randy Dunlap wrote:
> @@ -400,6 +400,10 @@ void mark_page_accessed(struct page *pag
>  }
>  EXPORT_SYMBOL(mark_page_accessed);
>  
> +/**
> + * __lru_cache_add: add a page to the page lists
> + * @page: the page to add
> + */
>  static void __lru_cache_add(struct page *page)
>  {
>  	struct pagevec *pvec = &get_cpu_var(lru_add_pvec);
> @@ -410,10 +414,6 @@ static void __lru_cache_add(struct page
>  	put_cpu_var(lru_add_pvec);
>  }
>  
> -/**
> - * lru_cache_add: add a page to the page lists
> - * @page: the page to add
> - */
>  void lru_cache_add_anon(struct page *page)
>  {
>  	if (PageActive(page))

I don't see the point in adding kernel-doc for a static function while
deleting it for a non-static function?  I'd change the name of the
function in the second hunk and drop the first hunk.

Also, the comment doesn't actually fit the kernel-doc format (colon
versus hyphen; missing capitalisation and full-stop).

> @@ -913,11 +913,11 @@ EXPORT_SYMBOL(__pagevec_lru_add);
>   * @pvec:	Where the resulting entries are placed
>   * @mapping:	The address_space to search
>   * @start:	The starting entry index
> - * @nr_entries:	The maximum number of entries
> + * @nr_pages:	The maximum number of entries
>   * @indices:	The cache indices corresponding to the entries in @pvec
>   *
>   * pagevec_lookup_entries() will search for and return a group of up
> - * to @nr_entries pages and shadow entries in the mapping.  All
> + * to @nr_pages pages and shadow entries in the mapping.  All
>   * entries are placed in @pvec.  pagevec_lookup_entries() takes a
>   * reference against actual pages in @pvec.
>   *

I think the documentation has the right name here; it is the number of
entries and not the number of pages which is returned.  We should change
the code to match the documentation here ;-)