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

[Ingo Molnar <mingo@kernel.org>]

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

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