Re: [PATCH] bus: mhi: clean up some kernel-doc warnings

On Sun, Jul 19, 2026 at 03:32:31PM -0700, Randy Dunlap wrote:
> Clean up some kernel-doc comments and warnings:
> - use correct format for struct members
> - add one struct member description
> - add one function parameter description
> - mark one enum as private
> - add a leading '*' on one kernel-doc line
> 
> Fixes these warnings:
> Warning: include/linux/mhi.h:108 struct member 'target_link_speed' not
>  described in 'mhi_link_info'
> Warning: include/linux/mhi.h:108 struct member 'target_link_width' not
>  described in 'mhi_link_info'
> Warning: ../include/linux/mhi.h:159 Enum value 'MHI_STATE_MAX' not
>  described in enum 'mhi_state'
> Warning: ../include/linux/mhi.h:212 bad line: for UL channels, multiple
>  of 8 ring elements for DL channels
> Warning: ../include/linux/mhi.h:236 struct member 'wake_capable' not
>  described in 'mhi_channel_config'
> Warning: ../include/linux/mhi.h:449 struct member 'M0' not described
>  in 'mhi_controller'
> Warning: ../include/linux/mhi.h:449 struct member 'M2' not described
>  in 'mhi_controller'
> Warning: ../include/linux/mhi.h:449 struct member 'M3' not described
>  in 'mhi_controller'
> Warning: ../include/linux/mhi.h:528 struct member 'id_table' not described
>  in 'mhi_driver'
> Warning: ../include/linux/mhi.h:543 function parameter 'mhi_cntrl' not
>  described in 'mhi_free_controller'
> 
> Signed-off-by: Randy Dunlap <[email protected]>

Applied to mhi-next!

- Mani

> ---
> Cc: Manivannan Sadhasivam <[email protected]>
> Cc: Jeff Hugo <[email protected]>
> Cc: [email protected]
> Cc: [email protected]
> 
>  include/linux/mhi.h |   15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)
> 
> --- linux-next-20260717.orig/include/linux/mhi.h
> +++ linux-next-20260717/include/linux/mhi.h
> @@ -117,8 +117,8 @@ struct image_info {
>  
>  /**
>   * struct mhi_link_info - BW requirement
> - * target_link_speed - Link speed as defined by TLS bits in LinkControl reg
> - * target_link_width - Link width as defined by NLW bits in LinkStatus reg
> + * @target_link_speed: Link speed as defined by TLS bits in LinkControl reg
> + * @target_link_width: Link width as defined by NLW bits in LinkStatus reg
>   */
>  struct mhi_link_info {
>  	unsigned int target_link_speed;
> @@ -173,6 +173,7 @@ enum mhi_state {
>  	MHI_STATE_M3_FAST = 0x6,
>  	MHI_STATE_BHI = 0x7,
>  	MHI_STATE_SYS_ERR = 0xFF,
> +	/* private: */
>  	MHI_STATE_MAX,
>  };
>  
> @@ -227,12 +228,12 @@ enum mhi_db_brst_mode {
>   * @type: Channel type
>   * @ee_mask: Execution Environment mask for this channel
>   * @pollcfg: Polling configuration for burst mode.  0 is default.  milliseconds
> -	     for UL channels, multiple of 8 ring elements for DL channels
> + *	     for UL channels, multiple of 8 ring elements for DL channels
>   * @doorbell: Doorbell mode
>   * @lpm_notify: The channel master requires low power mode notifications
>   * @offload_channel: The client manages the channel completely
>   * @doorbell_mode_switch: Channel switches to doorbell mode on M0 transition
> - * @wake-capable: Channel capable of waking up the system
> + * @wake_capable: Channel capable of waking up the system
>   */
>  struct mhi_channel_config {
>  	char *name;
> @@ -350,7 +351,9 @@ struct mhi_controller_config {
>   * @dev_state: MHI device state
>   * @dev_wake: Device wakeup count
>   * @pending_pkts: Pending packets for the controller
> - * @M0, M2, M3: Counters to track number of device MHI state changes
> + * @M0: Counter to track number of device MHI state changes
> + * @M2: Counter to track number of device MHI state changes
> + * @M3: Counter to track number of device MHI state changes
>   * @transition_list: List of MHI state transitions
>   * @transition_lock: Lock for protecting MHI state transition list
>   * @wlock: Lock for protecting device wakeup
> @@ -507,6 +510,7 @@ struct mhi_result {
>  
>  /**
>   * struct mhi_driver - Structure representing a MHI client driver
> + * @id_table: table of MHI channel names that a driver supports
>   * @probe: CB function for client driver probe function
>   * @remove: CB function for client driver remove function
>   * @ul_xfer_cb: CB function for UL data transfer
> @@ -538,6 +542,7 @@ struct mhi_controller *mhi_alloc_control
>  
>  /**
>   * mhi_free_controller - Free the MHI Controller structure
> + * @mhi_cntrl: MHI controller to free
>   * Free the mhi_controller structure which was previously allocated
>   */
>  void mhi_free_controller(struct mhi_controller *mhi_cntrl);

-- 
மணிவண்ணன் சதாசிவம்