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

[Randy Dunlap <rdunlap@infradead.org>]

On 4/11/21 11:35 AM, Matthew Wilcox wrote:
> 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().

I'll certainly add the doc for tlb_gather_mmu_fullmm()  -- don't want to
lose that @fullmm: comment.

> 
>> --- 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.

Done.

>>  {
>> --- 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?
> 

Sounds good. Thanks. v2 coming soon.

-- 
~Randy