[PATCH 00/35] Reorganize kerneldoc parameter names

[PATCH 00/35] Reorganize kerneldoc parameter names

[Julia Lawall]

Reorganize kerneldoc parameter names to match the parameter
order in the function header.

The misordered cases were identified using the following
Coccinelle semantic patch:

// <smpl>
@initialize:ocaml@
@@

let parse_doc l =
  let pieces = List.map String.trim (String.split_on_char '*' l) in
  let l = String.concat " " pieces in
  match String.split_on_char ':' l with
    x::xs -> x
  | _ -> ""

let params ps =
  List.rev
    (List.fold_left
       (fun prev (pm,_) ->
	 let ty =
	   String.trim(Pretty_print_c.string_of_fullType pm.Ast_c.p_type) in
	 if ty = "void" && pm.Ast_c.p_namei = None
	 then prev
	 else
	   let name =
	     match pm.Ast_c.p_namei with
	       Some name -> name
	     | None -> failwith "function parameter has no name" in
	   (String.trim (Pretty_print_c.string_of_name name),ty)::prev)
       [] ps)

@r@
comments c;
identifier fn;
position p;
parameter list ps;
type T;
@@

T@c fn@p(ps) { ... }

@script:ocaml@
p << r.p;
c << r.c;
(_,ps) << r.ps;
@@

let isdoc c ps =
  List.length ps > 1 &&
  (let c = String.trim c in
  String.length c > 3 && String.sub c 0 3 = "/**" && String.get c 3 != '*') in

let subset l1 l2 =
  List.for_all (fun x -> List.mem x l2) l1 in

let (cb,cm,ca) = List.hd c in
match List.rev cb with
  c::_ when isdoc c ps ->
    let pieces = String.split_on_char '@' c in
    (match pieces with
      _::tl ->
	let d_names = List.map parse_doc tl in
	(* check parameters *)
	let p_names = List.map fst (params ps) in
	if d_names <> [] && not(d_names = p_names)
	then
	  begin
	    if List.sort compare d_names = List.sort compare p_names
	    then Coccilib.print_main "out of order" p
	    else if subset d_names p_names
	    then Coccilib.print_main "doc is missing a parameter" p
	    else if subset d_names p_names
	    then Coccilib.print_main "doc has an extra parameter" p
	  end
    | _ -> ())
| _ -> ()
// </smpl>

---

 arch/arm/mach-omap2/prm2xxx_3xxx.c              |    1 -
 arch/powerpc/platforms/ps3/interrupt.c          |    2 +-
 arch/powerpc/platforms/ps3/repository.c         |    2 +-
 drivers/base/firmware_loader/main.c             |    2 +-
 drivers/comedi/drivers/comedi_8254.c            |    2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c          |    2 +-
 drivers/gpu/drm/amd/display/dc/core/dc.c        |    2 +-
 drivers/gpu/drm/drm_gem_framebuffer_helper.c    |    3 +--
 drivers/gpu/drm/drm_gpuvm.c                     |    2 +-
 drivers/gpu/drm/radeon/radeon_ib.c              |    2 +-
 drivers/iommu/iommu.c                           |    2 +-
 drivers/leds/leds-gpio-register.c               |    2 +-
 drivers/mfd/atmel-smc.c                         |    4 ++--
 drivers/misc/mei/bus.c                          |    2 +-
 drivers/mtd/ubi/eba.c                           |    2 +-
 drivers/net/ethernet/broadcom/bnxt/bnxt_hwrm.c  |    2 +-
 drivers/net/ethernet/intel/e1000/e1000_hw.c     |    2 +-
 drivers/net/ethernet/intel/i40e/i40e_common.c   |    7 +++----
 drivers/net/ethernet/intel/ice/ice_common.c     |    2 +-
 drivers/net/ethernet/intel/ixgbe/ixgbe_common.c |    2 +-
 drivers/nvdimm/dimm_devs.c                      |    2 +-
 drivers/pci/hotplug/pci_hotplug_core.c          |    2 +-
 drivers/pinctrl/pinmux.c                        |    2 +-
 drivers/slimbus/messaging.c                     |    2 +-
 drivers/soc/qcom/qmi_interface.c                |    2 +-
 drivers/soundwire/stream.c                      |    2 +-
 drivers/usb/gadget/config.c                     |    4 ++--
 fs/char_dev.c                                   |    2 +-
 fs/dcache.c                                     |    4 ++--
 fs/seq_file.c                                   |    2 +-
 kernel/audit.c                                  |    2 +-
 kernel/resource.c                               |    2 +-
 kernel/sysctl.c                                 |    1 -
 kernel/trace/ring_buffer.c                      |    2 +-
 lib/lru_cache.c                                 |    2 +-
 lib/maple_tree.c                                |    2 +-
 mm/mmu_notifier.c                               |    2 +-
 net/dccp/feat.c                                 |    2 +-
 net/mac80211/mesh_hwmp.c                        |    6 +++---
 net/mac80211/mesh_pathtbl.c                     |   10 +++++-----
 net/socket.c                                    |    2 +-
 net/sunrpc/xprt.c                               |    2 +-
 net/tipc/link.c                                 |   14 +++++++-------
 net/tipc/msg.c                                  |    2 +-
 sound/pci/hda/hda_codec.c                       |    2 +-
 45 files changed, 60 insertions(+), 64 deletions(-)

[PATCH 08/35] fs: Reorganize kerneldoc parameter names

[Julia Lawall]

Reorganize kerneldoc parameter names to match the parameter
order in the function header.

Problems identified using Coccinelle.

Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>

---
 fs/char_dev.c |    2 +-
 fs/dcache.c   |    4 ++--
 fs/seq_file.c |    2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/fs/char_dev.c b/fs/char_dev.c
index 57cc096c498a..c2ddb998f3c9 100644
--- a/fs/char_dev.c
+++ b/fs/char_dev.c
@@ -562,8 +562,8 @@ int cdev_device_add(struct cdev *cdev, struct device *dev)
 
 /**
  * cdev_device_del() - inverse of cdev_device_add
- * @dev: the device structure
  * @cdev: the cdev structure
+ * @dev: the device structure
  *
  * cdev_device_del() is a helper function to call cdev_del and device_del.
  * It should be used whenever cdev_device_add is used.
diff --git a/fs/dcache.c b/fs/dcache.c
index d7f6866f5f52..2894b30d8e40 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -2039,8 +2039,8 @@ EXPORT_SYMBOL(d_obtain_root);
 
 /**
  * d_add_ci - lookup or allocate new dentry with case-exact name
- * @inode:  the inode case-insensitive lookup has found
  * @dentry: the negative dentry that was passed to the parent's lookup func
+ * @inode:  the inode case-insensitive lookup has found
  * @name:   the case-exact name to be associated with the returned dentry
  *
  * This is to avoid filling the dcache with case-insensitive names to the
@@ -2093,8 +2093,8 @@ EXPORT_SYMBOL(d_add_ci);
 
 /**
  * d_same_name - compare dentry name with case-exact name
- * @parent: parent dentry
  * @dentry: the negative dentry that was passed to the parent's lookup func
+ * @parent: parent dentry
  * @name:   the case-exact name to be associated with the returned dentry
  *
  * Return: true if names are same, or false
diff --git a/fs/seq_file.c b/fs/seq_file.c
index e676c8b0cf5d..8bbb1ad46335 100644
--- a/fs/seq_file.c
+++ b/fs/seq_file.c
@@ -343,8 +343,8 @@ EXPORT_SYMBOL(seq_lseek);
 
 /**
  *	seq_release -	free the structures associated with sequential file.
- *	@file: file in question
  *	@inode: its inode
+ *	@file: file in question
  *
  *	Frees the structures associated with sequential file; can be used
  *	as ->f_op->release() if you don't have private data to destroy.

[PATCH 09/35] sysctl: Reorganize kerneldoc parameter names

[Julia Lawall]

Reorganize kerneldoc parameter names to match the parameter
order in the function header.

Problems identified using Coccinelle.

Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>

---
 kernel/sysctl.c |    1 -
 1 file changed, 1 deletion(-)

diff --git a/kernel/sysctl.c b/kernel/sysctl.c
index 79e6cb1d5c48..5c9202cb8f59 100644
--- a/kernel/sysctl.c
+++ b/kernel/sysctl.c
@@ -1305,7 +1305,6 @@ int proc_dointvec_userhz_jiffies(const struct ctl_table *table, int write,
  * @write: %TRUE if this is a write to the sysctl file
  * @buffer: the user buffer
  * @lenp: the size of the user buffer
- * @ppos: file position
  * @ppos: the current position in the file
  *
  * Reads/writes up to table->maxlen/sizeof(unsigned int) integer

Re: (subset) [PATCH 08/35] fs: Reorganize kerneldoc parameter names

[Christian Brauner]

On Mon, 30 Sep 2024 13:20:54 +0200, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> Problems identified using Coccinelle.
> 
> 

Applied to the vfs.misc branch of the vfs/vfs.git tree.
Patches in the vfs.misc branch should appear in linux-next soon.

Please report any outstanding bugs that were missed during review in a
new review to the original patch series allowing us to drop it.

It's encouraged to provide Acked-bys and Reviewed-bys even though the
patch has now been applied. If possible patch trailers will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. If in doubt, please check the listed branch.

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git
branch: vfs.misc

[08/35] fs: Reorganize kerneldoc parameter names
        https://git.kernel.org/vfs/vfs/c/513f3387a9f3

Re: [PATCH 08/35] fs: Reorganize kerneldoc parameter names

[Jan Kara]

On Mon 30-09-24 13:20:54, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> Problems identified using Coccinelle.
> 
> Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>

Looks good. Feel free to add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> 
> ---
>  fs/char_dev.c |    2 +-
>  fs/dcache.c   |    4 ++--
>  fs/seq_file.c |    2 +-
>  3 files changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/fs/char_dev.c b/fs/char_dev.c
> index 57cc096c498a..c2ddb998f3c9 100644
> --- a/fs/char_dev.c
> +++ b/fs/char_dev.c
> @@ -562,8 +562,8 @@ int cdev_device_add(struct cdev *cdev, struct device *dev)
>  
>  /**
>   * cdev_device_del() - inverse of cdev_device_add
> - * @dev: the device structure
>   * @cdev: the cdev structure
> + * @dev: the device structure
>   *
>   * cdev_device_del() is a helper function to call cdev_del and device_del.
>   * It should be used whenever cdev_device_add is used.
> diff --git a/fs/dcache.c b/fs/dcache.c
> index d7f6866f5f52..2894b30d8e40 100644
> --- a/fs/dcache.c
> +++ b/fs/dcache.c
> @@ -2039,8 +2039,8 @@ EXPORT_SYMBOL(d_obtain_root);
>  
>  /**
>   * d_add_ci - lookup or allocate new dentry with case-exact name
> - * @inode:  the inode case-insensitive lookup has found
>   * @dentry: the negative dentry that was passed to the parent's lookup func
> + * @inode:  the inode case-insensitive lookup has found
>   * @name:   the case-exact name to be associated with the returned dentry
>   *
>   * This is to avoid filling the dcache with case-insensitive names to the
> @@ -2093,8 +2093,8 @@ EXPORT_SYMBOL(d_add_ci);
>  
>  /**
>   * d_same_name - compare dentry name with case-exact name
> - * @parent: parent dentry
>   * @dentry: the negative dentry that was passed to the parent's lookup func
> + * @parent: parent dentry
>   * @name:   the case-exact name to be associated with the returned dentry
>   *
>   * Return: true if names are same, or false
> diff --git a/fs/seq_file.c b/fs/seq_file.c
> index e676c8b0cf5d..8bbb1ad46335 100644
> --- a/fs/seq_file.c
> +++ b/fs/seq_file.c
> @@ -343,8 +343,8 @@ EXPORT_SYMBOL(seq_lseek);
>  
>  /**
>   *	seq_release -	free the structures associated with sequential file.
> - *	@file: file in question
>   *	@inode: its inode
> + *	@file: file in question
>   *
>   *	Frees the structures associated with sequential file; can be used
>   *	as ->f_op->release() if you don't have private data to destroy.
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: (subset) [PATCH 00/35] Reorganize kerneldoc parameter names

[Bjorn Andersson]

On Mon, 30 Sep 2024 13:20:46 +0200, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> The misordered cases were identified using the following
> Coccinelle semantic patch:
> 
> // <smpl>
> @initialize:ocaml@
> @@
> 
> [...]

Applied, thanks!

[24/35] soc: qcom: qmi: Reorganize kerneldoc parameter names
        commit: eea73fa08e69fec9cdc915592022bec6a9ac8ad7

Best regards,
-- 
Bjorn Andersson <andersson@kernel.org>

Re: [PATCH 09/35] sysctl: Reorganize kerneldoc parameter names

[Joel Granados]

On Mon, Sep 30, 2024 at 01:20:55PM +0200, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> Problems identified using Coccinelle.
> 
> Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
> 
> ---
>  kernel/sysctl.c |    1 -
>  1 file changed, 1 deletion(-)
> 
> diff --git a/kernel/sysctl.c b/kernel/sysctl.c
> index 79e6cb1d5c48..5c9202cb8f59 100644
> --- a/kernel/sysctl.c
> +++ b/kernel/sysctl.c
> @@ -1305,7 +1305,6 @@ int proc_dointvec_userhz_jiffies(const struct ctl_table *table, int write,
>   * @write: %TRUE if this is a write to the sysctl file
>   * @buffer: the user buffer
>   * @lenp: the size of the user buffer
> - * @ppos: file position
>   * @ppos: the current position in the file
>   *
>   * Reads/writes up to table->maxlen/sizeof(unsigned int) integer
> 
This looks good to me. Is it going to go into main line together with
the other 35 or should I take this one through sysctl subsystem?

Best

Signed-off-by: Joel Granados <joel.granados@kernel.com>

-- 

Joel Granados

Re: [PATCH 09/35] sysctl: Reorganize kerneldoc parameter names

[Julia Lawall]

On Tue, 22 Oct 2024, Joel Granados wrote:

> On Mon, Sep 30, 2024 at 01:20:55PM +0200, Julia Lawall wrote:
> > Reorganize kerneldoc parameter names to match the parameter
> > order in the function header.
> >
> > Problems identified using Coccinelle.
> >
> > Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
> >
> > ---
> >  kernel/sysctl.c |    1 -
> >  1 file changed, 1 deletion(-)
> >
> > diff --git a/kernel/sysctl.c b/kernel/sysctl.c
> > index 79e6cb1d5c48..5c9202cb8f59 100644
> > --- a/kernel/sysctl.c
> > +++ b/kernel/sysctl.c
> > @@ -1305,7 +1305,6 @@ int proc_dointvec_userhz_jiffies(const struct ctl_table *table, int write,
> >   * @write: %TRUE if this is a write to the sysctl file
> >   * @buffer: the user buffer
> >   * @lenp: the size of the user buffer
> > - * @ppos: file position
> >   * @ppos: the current position in the file
> >   *
> >   * Reads/writes up to table->maxlen/sizeof(unsigned int) integer
> >
> This looks good to me. Is it going to go into main line together with
> the other 35 or should I take this one through sysctl subsystem?

Please take it,

julia

>
> Best
>
> Signed-off-by: Joel Granados <joel.granados@kernel.com>
>
> --
>
> Joel Granados
>

Re: Re: [PATCH 09/35] sysctl: Reorganize kerneldoc parameter names

[Joel Granados]

On Tue, Oct 22, 2024 at 01:13:25PM -0700, Julia Lawall wrote:
> 
> 
> On Tue, 22 Oct 2024, Joel Granados wrote:
> 
> > On Mon, Sep 30, 2024 at 01:20:55PM +0200, Julia Lawall wrote:
> > > Reorganize kerneldoc parameter names to match the parameter
> > > order in the function header.
> > >
> > > Problems identified using Coccinelle.
> > >
> > > Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr>
> > >
> > > ---
> > >  kernel/sysctl.c |    1 -
> > >  1 file changed, 1 deletion(-)
> > >
> > > diff --git a/kernel/sysctl.c b/kernel/sysctl.c
> > > index 79e6cb1d5c48..5c9202cb8f59 100644
> > > --- a/kernel/sysctl.c
> > > +++ b/kernel/sysctl.c
> > > @@ -1305,7 +1305,6 @@ int proc_dointvec_userhz_jiffies(const struct ctl_table *table, int write,
> > >   * @write: %TRUE if this is a write to the sysctl file
> > >   * @buffer: the user buffer
> > >   * @lenp: the size of the user buffer
> > > - * @ppos: file position
> > >   * @ppos: the current position in the file
> > >   *
> > >   * Reads/writes up to table->maxlen/sizeof(unsigned int) integer
> > >
> > This looks good to me. Is it going to go into main line together with
> > the other 35 or should I take this one through sysctl subsystem?
> 
> Please take it,

Ok. I added to the sysctl-next branch going into the next release.

thx.

Best

-- 

Joel Granados

Re: (subset) [PATCH 00/35] Reorganize kerneldoc parameter names

[Michael Ellerman]

On Mon, 30 Sep 2024 13:20:46 +0200, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> The misordered cases were identified using the following
> Coccinelle semantic patch:
> 
> // <smpl>
> @initialize:ocaml@
> @@
> 
> [...]

Applied to powerpc/next.

[11/35] powerpc/ps3: Reorganize kerneldoc parameter names
        https://git.kernel.org/powerpc/c/276e036e5844116e563fa90f676c625bb742cc57

cheers

Re: (subset) [PATCH 00/35] Reorganize kerneldoc parameter names

[Srinivas Kandagatla]

On Mon, 30 Sep 2024 13:20:46 +0200, Julia Lawall wrote:
> Reorganize kerneldoc parameter names to match the parameter
> order in the function header.
> 
> The misordered cases were identified using the following
> Coccinelle semantic patch:
> 
> // <smpl>
> @initialize:ocaml@
> @@
> 
> [...]

Applied, thanks!

[31/35] slimbus: messaging: Reorganize kerneldoc parameter names
        commit: 52d3d7f7a77ee9afc6a846b415790e13e1434847

Best regards,
-- 
Srinivas Kandagatla <srinivas.kandagatla@linaro.org>