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

From: Randy Dunlap
Date: Mon Jan 29 2018 - 18:54:52 EST


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