Re: [PATCH RESEND 1/4] x86/mm: pgtable: Fix W=1 build kernel-doc warnings

[Shivank Garg <shivankg@amd.com>]

On 5/15/2025 8:36 PM, Ingo Molnar wrote:
> 
> * Shivank Garg <shivankg@amd.com> wrote:
> 
>>> Also, similar errors are elsewhere as well.
>>
>> I'm sorry for missing these details in the previous revision.
>> I'm changing the first letter of variable description to capital.
>>
>> https://docs.kernel.org/doc-guide/kernel-doc.html
>> /**
>>  * function_name() - Brief description of function.
>>  * @arg1: Describe the first argument.
>>  * @arg2: Describe the second argument.
>>  *        One can provide multiple line descriptions
>>  *        for arguments.
>>
>> Function description also starts with capital letter in the doc-guide
>> and other kernel places so this should make it consistent.
> 
> Thank you! This version is much more complete. There were a few other 
> things missing, quite a few of them pre-existing, which I fixed up in 
> the commit (see the delta patch below).
> 
> Note that I standardized on a kernel-doc style variant without full 
> stops for simple singular sentences. This is what most of the x86 code 
> and the core kernel is doing, and it's contrary to the kernel-doc.html 
> recommendation - but you couldn't really have known that.
> 

Thank you for the detailed review and fixups.

Best Regards,
Shivank

> Thanks,
> 
> 	Ingo
> 
> =====================>
>  arch/x86/mm/pgtable.c | 50 +++++++++++++++++++++++++-------------------------
>  1 file changed, 25 insertions(+), 25 deletions(-)
> 
> diff --git a/arch/x86/mm/pgtable.c b/arch/x86/mm/pgtable.c
> index 9aa3c60c6afa..59c42dec7076 100644
> --- a/arch/x86/mm/pgtable.c
> +++ b/arch/x86/mm/pgtable.c
> @@ -543,11 +543,11 @@ pud_t pudp_invalidate(struct vm_area_struct *vma, unsigned long address,
>  #endif
>  
>  /**
> - * reserve_top_address - Reserves a hole in the top of kernel address space
> - * @reserve: Size of hole to reserve.
> + * reserve_top_address - Reserve a hole in the top of the kernel address space
> + * @reserve: Size of hole to reserve
>   *
>   * Can be used to relocate the fixmap area and poke a hole in the top
> - * of kernel address space to make room for a hypervisor.
> + * of the kernel address space to make room for a hypervisor.
>   */
>  void __init reserve_top_address(unsigned long reserve)
>  {
> @@ -594,10 +594,10 @@ void native_set_fixmap(unsigned /* enum fixed_addresses */ idx,
>  #ifdef CONFIG_HAVE_ARCH_HUGE_VMAP
>  #ifdef CONFIG_X86_5LEVEL
>  /**
> - * p4d_set_huge - Setup kernel P4D mapping
> - * @p4d: Pointer to the P4D entry.
> - * @addr: Virtual address associated with the P4D entry.
> - * @prot: Protection bits to use.
> + * p4d_set_huge - Set up kernel P4D mapping
> + * @p4d: Pointer to the P4D entry
> + * @addr: Virtual address associated with the P4D entry
> + * @prot: Protection bits to use
>   *
>   * No 512GB pages yet -- always return 0
>   */
> @@ -608,7 +608,7 @@ int p4d_set_huge(p4d_t *p4d, phys_addr_t addr, pgprot_t prot)
>  
>  /**
>   * p4d_clear_huge - Clear kernel P4D mapping when it is set
> - * @p4d: Pointer to the P4D entry to clear.
> + * @p4d: Pointer to the P4D entry to clear
>   *
>   * No 512GB pages yet -- do nothing
>   */
> @@ -618,10 +618,10 @@ void p4d_clear_huge(p4d_t *p4d)
>  #endif
>  
>  /**
> - * pud_set_huge - Setup kernel PUD mapping
> - * @pud: Pointer to the PUD entry.
> - * @addr: Virtual address associated with the PUD entry.
> - * @prot: Protection bits to use.
> + * pud_set_huge - Set up kernel PUD mapping
> + * @pud: Pointer to the PUD entry
> + * @addr: Virtual address associated with the PUD entry
> + * @prot: Protection bits to use
>   *
>   * MTRRs can override PAT memory types with 4KiB granularity. Therefore, this
>   * function sets up a huge page only if the complete range has the same MTRR
> @@ -652,10 +652,10 @@ int pud_set_huge(pud_t *pud, phys_addr_t addr, pgprot_t prot)
>  }
>  
>  /**
> - * pmd_set_huge - Setup kernel PMD mapping
> - * @pmd: Pointer to the PMD entry.
> - * @addr: Virtual address associated with the PMD entry.
> - * @prot: Protection bits to use.
> + * pmd_set_huge - Set up kernel PMD mapping
> + * @pmd: Pointer to the PMD entry
> + * @addr: Virtual address associated with the PMD entry
> + * @prot: Protection bits to use
>   *
>   * See text over pud_set_huge() above.
>   *
> @@ -717,11 +717,11 @@ int pmd_clear_huge(pmd_t *pmd)
>  
>  #ifdef CONFIG_X86_64
>  /**
> - * pud_free_pmd_page - Clear pud entry and free pmd page.
> - * @pud: Pointer to a PUD.
> - * @addr: Virtual address associated with pud.
> + * pud_free_pmd_page - Clear PUD entry and free PMD page
> + * @pud: Pointer to a PUD
> + * @addr: Virtual address associated with PUD
>   *
> - * Context: The pud range has been unmapped and TLB purged.
> + * Context: The PUD range has been unmapped and TLB purged.
>   * Return: 1 if clearing the entry succeeded. 0 otherwise.
>   *
>   * NOTE: Callers must allow a single page allocation.
> @@ -764,11 +764,11 @@ int pud_free_pmd_page(pud_t *pud, unsigned long addr)
>  }
>  
>  /**
> - * pmd_free_pte_page - Clear pmd entry and free pte page.
> - * @pmd: Pointer to a PMD.
> - * @addr: Virtual address associated with pmd.
> + * pmd_free_pte_page - Clear PMD entry and free PTE page.
> + * @pmd: Pointer to the PMD
> + * @addr: Virtual address associated with PMD
>   *
> - * Context: The pmd range has been unmapped and TLB purged.
> + * Context: The PMD range has been unmapped and TLB purged.
>   * Return: 1 if clearing the entry succeeded. 0 otherwise.
>   */
>  int pmd_free_pte_page(pmd_t *pmd, unsigned long addr)
> @@ -790,7 +790,7 @@ int pmd_free_pte_page(pmd_t *pmd, unsigned long addr)
>  
>  /*
>   * Disable free page handling on x86-PAE. This assures that ioremap()
> - * does not update sync'd pmd entries. See vmalloc_sync_one().
> + * does not update sync'd PMD entries. See vmalloc_sync_one().
>   */
>  int pmd_free_pte_page(pmd_t *pmd, unsigned long addr)
>  {