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

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

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Fix some basic kernel-doc notation in mm/swap.c:
- make function names in kernel-doc notation match the functions
- make function parameter names in kernel-doc match the actual parameters

Fix function kernel-doc to match the change in commit 67fd707f4681:
- drop the kernel-doc notation for @nr_pages from pagevec_lookup_range()
  and correct the function description for that change

Fixes 67fd707f4681:
    ("mm: remove nr_pages argument from pagevec_lookup_{,range}_tag()")

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jan Kara <jack@suse.cz>
---
 mm/swap.c |   17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

--- lnx-415.orig/mm/swap.c
+++ lnx-415/mm/swap.c
@@ -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))
@@ -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.
  *
@@ -965,9 +965,8 @@ void pagevec_remove_exceptionals(struct
  * @mapping:	The address_space to search
  * @start:	The starting page index
  * @end:	The final page index
- * @nr_pages:	The maximum number of pages
  *
- * pagevec_lookup_range() will search for and return a group of up to @nr_pages
+ * pagevec_lookup_range() will search for & return a group of up to PAGEVEC_SIZE
  * pages in the mapping starting from index @start and upto index @end
  * (inclusive).  The pages are placed in @pvec.  pagevec_lookup() takes a
  * reference against the pages in @pvec.
@@ -977,7 +976,7 @@ void pagevec_remove_exceptionals(struct
  * also update @start to index the next page for the traversal.
  *
  * pagevec_lookup_range() returns the number of pages which were found. If this
- * number is smaller than @nr_pages, the end of specified range has been
+ * number is smaller than PAGEVEC_SIZE, the end of specified range has been
  * reached.
  */
 unsigned pagevec_lookup_range(struct pagevec *pvec,

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

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

[Matthew Wilcox]

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 ;-)

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

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

[Randy Dunlap]

On 01/28/2018 09:15 PM, Matthew Wilcox wrote:
> 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.

Agree.

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

I certainly missed the colon vs. hyphen.  But I am not aware of any kernel-doc
format about capitalization or ending with a period -- and don't like them either.
Those descriptions usually are not complete sentences unless they are longer
descriptions.

>> @@ -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 ;-)

OK, will change that and send v2.

Thanks for the comments.
-- 
~Randy

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>