[PATCH v4 00/27]Fix several bad kernel-doc markups

[PATCH v4 00/27]Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

Kernel-doc has always be limited to a probably bad documented
rule:

The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.

On other words, if a C file would contain something like this:

	/**
	 * foo - function foo
	 * @args: foo args
	 */
	static inline void bar(int args);

	/**
	 * bar - function bar
	 * @args: foo args
	 */
	static inline void foo(void *args);


The output (in ReST format) will be:

	.. c:function:: void bar (int args)

	   function foo

	**Parameters**

	``int args``
	  foo args


	.. c:function:: void foo (void *args)

	   function bar

	**Parameters**

	``void *args``
	  foo args

Which is clearly a wrong result.  Before this changeset, 
not even a warning is produced on such cases.

As placing such markups just before the documented
data is a common practice, on most cases this is fine.

However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.

This has been happening for quite a while, as there are
lots of files with kernel-doc problems.

This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.

This series is based on current upstream tree.

@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on 
this series are independent from the other ones.

--

v4:

  - Patches got rebased and got some acks.

Mauro Carvalho Chehab (27):
  net: phy: fix kernel-doc markups
  net: datagram: fix some kernel-doc markups
  net: core: fix some kernel-doc markups
  s390: fix kernel-doc markups
  drm: fix some kernel-doc markups
  HSI: fix a kernel-doc markup
  IB: fix kernel-doc markups
  parport: fix a kernel-doc markup
  rapidio: fix kernel-doc a markup
  video: fix some kernel-doc markups
  fs: fix kernel-doc markups
  jbd2: fix kernel-doc markups
  pstore/zone: fix a kernel-doc markup
  completion: fix kernel-doc markups
  firmware: stratix10-svc: fix kernel-doc markups
  connector: fix a kernel-doc markup
  lib/crc7: fix a kernel-doc markup
  hrtimer: fix kernel-doc markups
  genirq: fix kernel-doc markups
  list: fix a typo at the kernel-doc markup
  memblock: fix kernel-doc markups
  w1: fix a kernel-doc markup
  resource: fix kernel-doc markups
  shed: fix kernel-doc markup
  mm: fix kernel-doc markups
  selftests: kselftest_harness.h: partially fix kernel-doc markups
  scripts: kernel-doc: validate kernel-doc markup with the actual names

 arch/s390/include/asm/ccwdev.h                |  2 +-
 arch/s390/include/asm/cio.h                   |  2 +-
 drivers/gpu/drm/drm_atomic_state_helper.c     |  2 +-
 drivers/gpu/drm/drm_connector.c               |  3 +-
 drivers/gpu/drm/drm_dp_helper.c               |  2 +-
 drivers/gpu/drm/drm_framebuffer.c             |  2 +-
 drivers/gpu/drm/drm_gem.c                     |  4 +-
 drivers/gpu/drm/drm_gem_vram_helper.c         |  2 +-
 drivers/gpu/drm/drm_mode_object.c             |  2 +-
 drivers/gpu/drm/drm_modes.c                   |  4 +-
 drivers/gpu/drm/drm_scdc_helper.c             |  2 +-
 drivers/gpu/drm/i915/display/intel_dpll_mgr.c |  2 +-
 drivers/gpu/drm/i915/i915_gem_evict.c         |  2 +-
 drivers/gpu/drm/i915/i915_perf.c              |  8 ++-
 drivers/gpu/drm/scheduler/sched_main.c        |  2 +-
 drivers/gpu/drm/v3d/v3d_sched.c               |  2 +-
 drivers/gpu/drm/vc4/vc4_bo.c                  |  2 +-
 drivers/hsi/hsi_core.c                        |  2 +-
 drivers/infiniband/core/cm.c                  |  5 +-
 drivers/infiniband/core/cq.c                  |  4 +-
 drivers/infiniband/core/iwpm_util.h           |  2 +-
 drivers/infiniband/core/sa_query.c            |  3 +-
 drivers/infiniband/core/verbs.c               |  4 +-
 drivers/infiniband/sw/rdmavt/ah.c             |  2 +-
 drivers/infiniband/sw/rdmavt/mcast.c          | 12 ++--
 drivers/infiniband/sw/rdmavt/qp.c             |  8 +--
 drivers/infiniband/ulp/iser/iscsi_iser.c      |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 .../ulp/opa_vnic/opa_vnic_vema_iface.c        |  2 +-
 drivers/infiniband/ulp/srpt/ib_srpt.h         |  2 +-
 drivers/net/phy/mdio_bus.c                    |  2 +-
 drivers/net/phy/phy-c45.c                     |  2 +-
 drivers/net/phy/phy.c                         |  2 +-
 drivers/net/phy/phy_device.c                  |  2 +-
 drivers/net/phy/phylink.c                     |  2 +-
 drivers/parport/share.c                       |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/video/fbdev/core/fbcmap.c             |  2 +-
 drivers/video/hdmi.c                          |  3 +-
 fs/dcache.c                                   | 72 +++++++++----------
 fs/inode.c                                    |  4 +-
 fs/jbd2/journal.c                             | 34 ++++-----
 fs/jbd2/transaction.c                         | 31 ++++----
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 ++--
 include/drm/drm_atomic_helper.h               |  4 +-
 include/drm/drm_connector.h                   |  2 +-
 include/drm/drm_device.h                      |  2 +-
 include/drm/drm_dsc.h                         |  3 +-
 include/drm/drm_gem_vram_helper.h             |  8 +--
 include/linux/completion.h                    | 10 ++-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/hrtimer.h                       |  6 +-
 include/linux/jbd2.h                          |  2 +-
 include/linux/list.h                          |  2 +-
 include/linux/memblock.h                      |  4 +-
 include/linux/netdevice.h                     | 11 ++-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/rdma/ib_verbs.h                       | 11 +++
 kernel/irq/chip.c                             |  2 +-
 kernel/irq/generic-chip.c                     |  2 +-
 kernel/resource.c                             | 24 ++++---
 kernel/sched/core.c                           | 16 ++---
 kernel/sched/fair.c                           |  2 +-
 kernel/time/hrtimer.c                         |  2 +-
 lib/crc7.c                                    |  2 +-
 mm/gup.c                                      | 24 ++++---
 mm/page_alloc.c                               | 16 ++---
 mm/truncate.c                                 | 10 ++-
 net/core/datagram.c                           |  2 +-
 net/core/dev.c                                |  4 +-
 net/core/skbuff.c                             |  2 +-
 net/ethernet/eth.c                            |  6 +-
 net/sunrpc/rpc_pipe.c                         |  3 +-
 scripts/kernel-doc                            | 62 +++++++++++-----
 tools/testing/selftests/kselftest_harness.h   | 22 +++---
 79 files changed, 350 insertions(+), 235 deletions(-)

-- 
2.28.0

[PATCH v4 04/27] s390: fix kernel-doc markups

[Mauro Carvalho Chehab]

fix one typo:
	ccw driver -> ccw_driver

and one function rename.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 arch/s390/include/asm/ccwdev.h | 2 +-
 arch/s390/include/asm/cio.h    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/arch/s390/include/asm/ccwdev.h b/arch/s390/include/asm/ccwdev.h
index bf605e1fcf6a..0495ac635ed5 100644
--- a/arch/s390/include/asm/ccwdev.h
+++ b/arch/s390/include/asm/ccwdev.h
@@ -100,41 +100,41 @@ struct ccw_device {
  */
 #define PE_NONE				0x0
 #define PE_PATH_GONE			0x1 /* A path is no longer available. */
 #define PE_PATH_AVAILABLE		0x2 /* A path has become available and
 					       was successfully verified. */
 #define PE_PATHGROUP_ESTABLISHED	0x4 /* A pathgroup was reset and had
 					       to be established again. */
 #define PE_PATH_FCES_EVENT		0x8 /* The FCES Status of a path has
 					     * changed. */
 
 /*
  * Possible CIO actions triggered by the unit check handler.
  */
 enum uc_todo {
 	UC_TODO_RETRY,
 	UC_TODO_RETRY_ON_NEW_PATH,
 	UC_TODO_STOP
 };
 
 /**
- * struct ccw driver - device driver for channel attached devices
+ * struct ccw_driver - device driver for channel attached devices
  * @ids: ids supported by this driver
  * @probe: function called on probe
  * @remove: function called on remove
  * @set_online: called when setting device online
  * @set_offline: called when setting device offline
  * @notify: notify driver of device state changes
  * @path_event: notify driver of channel path events
  * @shutdown: called at device shutdown
  * @prepare: prepare for pm state transition
  * @complete: undo work done in @prepare
  * @freeze: callback for freezing during hibernation snapshotting
  * @thaw: undo work done in @freeze
  * @restore: callback for restoring after hibernation
  * @uc_handler: callback for unit check handler
  * @driver: embedded device driver structure
  * @int_class: interruption class to use for accounting interrupts
  */
 struct ccw_driver {
 	struct ccw_device_id *ids;
 	int (*probe) (struct ccw_device *);
diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
index e36cb67d2441..ac02df906cae 100644
--- a/arch/s390/include/asm/cio.h
+++ b/arch/s390/include/asm/cio.h
@@ -312,41 +312,41 @@ struct node_descriptor {
 /* Device did not respond in time. */
 #define CIO_BOXED      0x0010
 
 /**
  * struct ccw_dev_id - unique identifier for ccw devices
  * @ssid: subchannel set id
  * @devno: device number
  *
  * This structure is not directly based on any hardware structure. The
  * hardware identifies a device by its device number and its subchannel,
  * which is in turn identified by its id. In order to get a unique identifier
  * for ccw devices across subchannel sets, @struct ccw_dev_id has been
  * introduced.
  */
 struct ccw_dev_id {
 	u8 ssid;
 	u16 devno;
 };
 
 /**
- * ccw_device_id_is_equal() - compare two ccw_dev_ids
+ * ccw_dev_id_is_equal() - compare two ccw_dev_ids
  * @dev_id1: a ccw_dev_id
  * @dev_id2: another ccw_dev_id
  * Returns:
  *  %1 if the two structures are equal field-by-field,
  *  %0 if not.
  * Context:
  *  any
  */
 static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
 				      struct ccw_dev_id *dev_id2)
 {
 	if ((dev_id1->ssid == dev_id2->ssid) &&
 	    (dev_id1->devno == dev_id2->devno))
 		return 1;
 	return 0;
 }
 
 /**
  * pathmask_to_pos() - find the position of the left-most bit in a pathmask
  * @mask: pathmask with at least one bit set
-- 
2.28.0

Re: [PATCH v4 04/27] s390: fix kernel-doc markups

[Cornelia Huck]

On Mon, 16 Nov 2020 11:18:00 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> fix one typo:
> 	ccw driver -> ccw_driver
> 
> and one function rename.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  arch/s390/include/asm/ccwdev.h | 2 +-
>  arch/s390/include/asm/cio.h    | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Re: [PATCH v4 04/27] s390: fix kernel-doc markups

[Vineeth Vijayan]

Thank you very much for the fix.

Reviewed-by: Vineeth Vijayan <vneethv@linux.ibm.com>



On 11/16/20 11:18 AM, Mauro Carvalho Chehab wrote:
> fix one typo:
> 	ccw driver -> ccw_driver
>
> and one function rename.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   arch/s390/include/asm/ccwdev.h | 2 +-
>   arch/s390/include/asm/cio.h    | 2 +-
>   2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/arch/s390/include/asm/ccwdev.h b/arch/s390/include/asm/ccwdev.h
> index bf605e1fcf6a..0495ac635ed5 100644
> --- a/arch/s390/include/asm/ccwdev.h
> +++ b/arch/s390/include/asm/ccwdev.h
> @@ -100,41 +100,41 @@ struct ccw_device {
>    */
>   #define PE_NONE				0x0
>   #define PE_PATH_GONE			0x1 /* A path is no longer available. */
>   #define PE_PATH_AVAILABLE		0x2 /* A path has become available and
>   					       was successfully verified. */
>   #define PE_PATHGROUP_ESTABLISHED	0x4 /* A pathgroup was reset and had
>   					       to be established again. */
>   #define PE_PATH_FCES_EVENT		0x8 /* The FCES Status of a path has
>   					     * changed. */
>   
>   /*
>    * Possible CIO actions triggered by the unit check handler.
>    */
>   enum uc_todo {
>   	UC_TODO_RETRY,
>   	UC_TODO_RETRY_ON_NEW_PATH,
>   	UC_TODO_STOP
>   };
>   
>   /**
> - * struct ccw driver - device driver for channel attached devices
> + * struct ccw_driver - device driver for channel attached devices
>    * @ids: ids supported by this driver
>    * @probe: function called on probe
>    * @remove: function called on remove
>    * @set_online: called when setting device online
>    * @set_offline: called when setting device offline
>    * @notify: notify driver of device state changes
>    * @path_event: notify driver of channel path events
>    * @shutdown: called at device shutdown
>    * @prepare: prepare for pm state transition
>    * @complete: undo work done in @prepare
>    * @freeze: callback for freezing during hibernation snapshotting
>    * @thaw: undo work done in @freeze
>    * @restore: callback for restoring after hibernation
>    * @uc_handler: callback for unit check handler
>    * @driver: embedded device driver structure
>    * @int_class: interruption class to use for accounting interrupts
>    */
>   struct ccw_driver {
>   	struct ccw_device_id *ids;
>   	int (*probe) (struct ccw_device *);
> diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
> index e36cb67d2441..ac02df906cae 100644
> --- a/arch/s390/include/asm/cio.h
> +++ b/arch/s390/include/asm/cio.h
> @@ -312,41 +312,41 @@ struct node_descriptor {
>   /* Device did not respond in time. */
>   #define CIO_BOXED      0x0010
>   
>   /**
>    * struct ccw_dev_id - unique identifier for ccw devices
>    * @ssid: subchannel set id
>    * @devno: device number
>    *
>    * This structure is not directly based on any hardware structure. The
>    * hardware identifies a device by its device number and its subchannel,
>    * which is in turn identified by its id. In order to get a unique identifier
>    * for ccw devices across subchannel sets, @struct ccw_dev_id has been
>    * introduced.
>    */
>   struct ccw_dev_id {
>   	u8 ssid;
>   	u16 devno;
>   };
>   
>   /**
> - * ccw_device_id_is_equal() - compare two ccw_dev_ids
> + * ccw_dev_id_is_equal() - compare two ccw_dev_ids
>    * @dev_id1: a ccw_dev_id
>    * @dev_id2: another ccw_dev_id
>    * Returns:
>    *  %1 if the two structures are equal field-by-field,
>    *  %0 if not.
>    * Context:
>    *  any
>    */
>   static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
>   				      struct ccw_dev_id *dev_id2)
>   {
>   	if ((dev_id1->ssid == dev_id2->ssid) &&
>   	    (dev_id1->devno == dev_id2->devno))
>   		return 1;
>   	return 0;
>   }
>   
>   /**
>    * pathmask_to_pos() - find the position of the left-most bit in a pathmask
>    * @mask: pathmask with at least one bit set

Re: [PATCH v4 04/27] s390: fix kernel-doc markups

[Vineeth Vijayan]

Heiko/Vasily will pick this up and will be part of the s390-tree patchset.

Regards
Vineeth


On 11/16/20 11:38 AM, Vineeth Vijayan wrote:
> Thank you very much for the fix.
>
> Reviewed-by: Vineeth Vijayan <vneethv@linux.ibm.com>
>
>
>
> On 11/16/20 11:18 AM, Mauro Carvalho Chehab wrote:
>> fix one typo:
>>     ccw driver -> ccw_driver
>>
>> and one function rename.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> ---
>>   arch/s390/include/asm/ccwdev.h | 2 +-
>>   arch/s390/include/asm/cio.h    | 2 +-
>>   2 files changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/arch/s390/include/asm/ccwdev.h 
>> b/arch/s390/include/asm/ccwdev.h
>> index bf605e1fcf6a..0495ac635ed5 100644
>> --- a/arch/s390/include/asm/ccwdev.h
>> +++ b/arch/s390/include/asm/ccwdev.h
>> @@ -100,41 +100,41 @@ struct ccw_device {
>>    */
>>   #define PE_NONE                0x0
>>   #define PE_PATH_GONE            0x1 /* A path is no longer 
>> available. */
>>   #define PE_PATH_AVAILABLE        0x2 /* A path has become available 
>> and
>>                              was successfully verified. */
>>   #define PE_PATHGROUP_ESTABLISHED    0x4 /* A pathgroup was reset 
>> and had
>>                              to be established again. */
>>   #define PE_PATH_FCES_EVENT        0x8 /* The FCES Status of a path has
>>                            * changed. */
>>     /*
>>    * Possible CIO actions triggered by the unit check handler.
>>    */
>>   enum uc_todo {
>>       UC_TODO_RETRY,
>>       UC_TODO_RETRY_ON_NEW_PATH,
>>       UC_TODO_STOP
>>   };
>>     /**
>> - * struct ccw driver - device driver for channel attached devices
>> + * struct ccw_driver - device driver for channel attached devices
>>    * @ids: ids supported by this driver
>>    * @probe: function called on probe
>>    * @remove: function called on remove
>>    * @set_online: called when setting device online
>>    * @set_offline: called when setting device offline
>>    * @notify: notify driver of device state changes
>>    * @path_event: notify driver of channel path events
>>    * @shutdown: called at device shutdown
>>    * @prepare: prepare for pm state transition
>>    * @complete: undo work done in @prepare
>>    * @freeze: callback for freezing during hibernation snapshotting
>>    * @thaw: undo work done in @freeze
>>    * @restore: callback for restoring after hibernation
>>    * @uc_handler: callback for unit check handler
>>    * @driver: embedded device driver structure
>>    * @int_class: interruption class to use for accounting interrupts
>>    */
>>   struct ccw_driver {
>>       struct ccw_device_id *ids;
>>       int (*probe) (struct ccw_device *);
>> diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
>> index e36cb67d2441..ac02df906cae 100644
>> --- a/arch/s390/include/asm/cio.h
>> +++ b/arch/s390/include/asm/cio.h
>> @@ -312,41 +312,41 @@ struct node_descriptor {
>>   /* Device did not respond in time. */
>>   #define CIO_BOXED      0x0010
>>     /**
>>    * struct ccw_dev_id - unique identifier for ccw devices
>>    * @ssid: subchannel set id
>>    * @devno: device number
>>    *
>>    * This structure is not directly based on any hardware structure. The
>>    * hardware identifies a device by its device number and its 
>> subchannel,
>>    * which is in turn identified by its id. In order to get a unique 
>> identifier
>>    * for ccw devices across subchannel sets, @struct ccw_dev_id has been
>>    * introduced.
>>    */
>>   struct ccw_dev_id {
>>       u8 ssid;
>>       u16 devno;
>>   };
>>     /**
>> - * ccw_device_id_is_equal() - compare two ccw_dev_ids
>> + * ccw_dev_id_is_equal() - compare two ccw_dev_ids
>>    * @dev_id1: a ccw_dev_id
>>    * @dev_id2: another ccw_dev_id
>>    * Returns:
>>    *  %1 if the two structures are equal field-by-field,
>>    *  %0 if not.
>>    * Context:
>>    *  any
>>    */
>>   static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
>>                         struct ccw_dev_id *dev_id2)
>>   {
>>       if ((dev_id1->ssid == dev_id2->ssid) &&
>>           (dev_id1->devno == dev_id2->devno))
>>           return 1;
>>       return 0;
>>   }
>>     /**
>>    * pathmask_to_pos() - find the position of the left-most bit in a 
>> pathmask
>>    * @mask: pathmask with at least one bit set

Re: [PATCH v4 00/27]Fix several bad kernel-doc markups

[Jakub Kicinski]

On Mon, 16 Nov 2020 11:17:56 +0100 Mauro Carvalho Chehab wrote:
> Kernel-doc has always be limited to a probably bad documented
> rule:
> 
> The kernel-doc markups should appear *imediatelly before* the
> function or data structure that it documents.

Applied 1-3 to net-next, thanks!