[PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Andy Shevchenko]

$ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h
warning: Function parameter or member 'rst' not described in 'dw_i2c_dev'
warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev'
warning: Function parameter or member 'flags' not described in 'dw_i2c_dev'
warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev'
warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev'
warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev'
warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/drivers/i2c/busses/i2c-designware-core.h b/drivers/i2c/busses/i2c-designware-core.h
index 60a2e750cee9..4b26cba40139 100644
--- a/drivers/i2c/busses/i2c-designware-core.h
+++ b/drivers/i2c/busses/i2c-designware-core.h
@@ -191,23 +191,26 @@ struct reset_control;
  * @cmd_complete: tx completion indicator
  * @clk: input reference clock
  * @pclk: clock required to access the registers
+ * @rst: optional reset for the controller
  * @slave: represent an I2C slave device
+ * @get_clk_rate_khz: callback to retrieve IP specific bus speed
  * @cmd_err: run time hadware error code
  * @msgs: points to an array of messages currently being transferred
  * @msgs_num: the number of elements in msgs
- * @msg_write_idx: the element index of the current tx message in the msgs
- *	array
+ * @msg_write_idx: the element index of the current tx message in the msgs array
  * @tx_buf_len: the length of the current tx buffer
  * @tx_buf: the current tx buffer
- * @msg_read_idx: the element index of the current rx message in the msgs
- *	array
+ * @msg_read_idx: the element index of the current rx message in the msgs array
  * @rx_buf_len: the length of the current rx buffer
  * @rx_buf: the current rx buffer
  * @msg_err: error status of the current transfer
  * @status: i2c master status, one of STATUS_*
  * @abort_source: copy of the TX_ABRT_SOURCE register
  * @irq: interrupt number for the i2c master
+ * @flags: platform specific flags like type of IO accessors or model
  * @adapter: i2c subsystem adapter node
+ * @functionality: I2C_FUNC_* ORed bits to reflect what controller does support
+ * @master_cfg: configuration for the master device
  * @slave_cfg: configuration for the slave device
  * @tx_fifo_depth: depth of the hardware tx fifo
  * @rx_fifo_depth: depth of the hardware rx fifo
@@ -228,7 +231,9 @@ struct reset_control;
  * @disable: function to disable the controller
  * @disable_int: function to disable all interrupts
  * @init: function to initialize the I2C hardware
+ * @set_sda_hold_time: callback to retrieve IP specific SDA hold timing
  * @mode: operation mode - DW_IC_MASTER or DW_IC_SLAVE
+ * @rinfo: I²C GPIO recovery information
  * @suspended: set to true if the controller is suspended
  *
  * HCNT and LCNT parameters can be used if the platform knows more accurate
-- 
2.33.0

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Jarkko Nikula]

On 11/12/21 2:34 PM, Andy Shevchenko wrote:
> $ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h
> warning: Function parameter or member 'rst' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'flags' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
>   drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++----
>   1 file changed, 9 insertions(+), 4 deletions(-)
> 
Acked-by: Jarkko Nikula <jarkko.nikula@linux.intel.com>

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Randy Dunlap]

On 11/12/21 4:34 AM, Andy Shevchenko wrote:
> $ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h
> warning: Function parameter or member 'rst' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'flags' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

Hi Andy,

Thanks for the kernel-doc fixes.

> ---
>   drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++----
>   1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/i2c/busses/i2c-designware-core.h b/drivers/i2c/busses/i2c-designware-core.h
> index 60a2e750cee9..4b26cba40139 100644
> --- a/drivers/i2c/busses/i2c-designware-core.h
> +++ b/drivers/i2c/busses/i2c-designware-core.h
> @@ -191,23 +191,26 @@ struct reset_control;
>    * @cmd_complete: tx completion indicator
>    * @clk: input reference clock
>    * @pclk: clock required to access the registers
> + * @rst: optional reset for the controller
>    * @slave: represent an I2C slave device
> + * @get_clk_rate_khz: callback to retrieve IP specific bus speed
>    * @cmd_err: run time hadware error code
>    * @msgs: points to an array of messages currently being transferred
>    * @msgs_num: the number of elements in msgs
> - * @msg_write_idx: the element index of the current tx message in the msgs
> - *	array
> + * @msg_write_idx: the element index of the current tx message in the msgs array
>    * @tx_buf_len: the length of the current tx buffer
>    * @tx_buf: the current tx buffer
> - * @msg_read_idx: the element index of the current rx message in the msgs
> - *	array
> + * @msg_read_idx: the element index of the current rx message in the msgs array
>    * @rx_buf_len: the length of the current rx buffer
>    * @rx_buf: the current rx buffer
>    * @msg_err: error status of the current transfer
>    * @status: i2c master status, one of STATUS_*
>    * @abort_source: copy of the TX_ABRT_SOURCE register
>    * @irq: interrupt number for the i2c master
> + * @flags: platform specific flags like type of IO accessors or model
>    * @adapter: i2c subsystem adapter node
> + * @functionality: I2C_FUNC_* ORed bits to reflect what controller does support
> + * @master_cfg: configuration for the master device
>    * @slave_cfg: configuration for the slave device
>    * @tx_fifo_depth: depth of the hardware tx fifo
>    * @rx_fifo_depth: depth of the hardware rx fifo
> @@ -228,7 +231,9 @@ struct reset_control;
>    * @disable: function to disable the controller
>    * @disable_int: function to disable all interrupts
>    * @init: function to initialize the I2C hardware
> + * @set_sda_hold_time: callback to retrieve IP specific SDA hold timing
>    * @mode: operation mode - DW_IC_MASTER or DW_IC_SLAVE
> + * @rinfo: I²C GPIO recovery information


Preferably:   "I2C"
like it is in thousands of places in the kernel source tree.

>    * @suspended: set to true if the controller is suspended
>    *
>    * HCNT and LCNT parameters can be used if the platform knows more accurate
> 


-- 
~Randy

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Andy Shevchenko]

On Fri, Nov 12, 2021 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
> On 11/12/21 4:34 AM, Andy Shevchenko wrote:

...

> > + * @rinfo: I²C GPIO recovery information
>
> Preferably:   "I2C"

Why?

> like it is in thousands of places in the kernel source tree.

UTF-8 has been established for more than a decade. I prefer to use the
proper form of the abbreviation (*).

*) Check UM10204.pdf.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Randy Dunlap]

On 11/12/21 8:26 AM, Andy Shevchenko wrote:
> On Fri, Nov 12, 2021 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>> On 11/12/21 4:34 AM, Andy Shevchenko wrote:
> 
> ...
> 
>>> + * @rinfo: I²C GPIO recovery information
>>
>> Preferably:   "I2C"
> 
> Why?

See below vvvvvvvvvvvvvvvvv:
>> like it is in thousands of places in the kernel source tree.


> UTF-8 has been established for more than a decade. I prefer to use the
> proper form of the abbreviation (*).
> 
> *) Check UM10204.pdf.
> 

Yes, I am aware of what is in the spec.

thanks.
-- 
~Randy

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Andy Shevchenko]

On Fri, Nov 12, 2021 at 08:43:16AM -0800, Randy Dunlap wrote:
> On 11/12/21 8:26 AM, Andy Shevchenko wrote:
> > On Fri, Nov 12, 2021 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
> > > On 11/12/21 4:34 AM, Andy Shevchenko wrote:

...

> > > > + * @rinfo: I²C GPIO recovery information
> > > 
> > > Preferably:   "I2C"
> > 
> > Why?
> 
> See below vvvvvvvvvvvvvvvvv:
> > > like it is in thousands of places in the kernel source tree.

When is it good point to start following the spec?

> > UTF-8 has been established for more than a decade. I prefer to use the
> > proper form of the abbreviation (*).
> > 
> > *) Check UM10204.pdf.
> 
> Yes, I am aware of what is in the spec.

Wolfram, what do you prefer?

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 173 bytes --]


> > Yes, I am aware of what is in the spec.
> 
> Wolfram, what do you prefer?

I prefer I2C. But it is more a reading habit. I would neither enforce
I2C nor I²C.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Randy Dunlap]

On 11/12/21 8:43 AM, Randy Dunlap wrote:
> On 11/12/21 8:26 AM, Andy Shevchenko wrote:
>> On Fri, Nov 12, 2021 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>> On 11/12/21 4:34 AM, Andy Shevchenko wrote:
>>
>> ...
>>
>>>> + * @rinfo: I²C GPIO recovery information
>>>
>>> Preferably:   "I2C"
>>
>> Why?
> 
> See below vvvvvvvvvvvvvvvvv:
>>> like it is in thousands of places in the kernel source tree.
> 
> 
>> UTF-8 has been established for more than a decade. I prefer to use the
>> proper form of the abbreviation (*).
>>
>> *) Check UM10204.pdf.


> > Yes, I am aware of what is in the spec.
> 
> Wolfram, what do you prefer?

>I prefer I2C. But it is more a reading habit. I would neither enforce
>I2C nor I²C.

OK, let's leave it as Andy sent it then.

Acked-by: Randy Dunlap <rdunla@infradead.org>


-- 
~Randy

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Andy Shevchenko]

On Mon, Nov 15, 2021 at 07:46:42AM -0800, Randy Dunlap wrote:
> On 11/12/21 8:43 AM, Randy Dunlap wrote:
> > On 11/12/21 8:26 AM, Andy Shevchenko wrote:
> > > On Fri, Nov 12, 2021 at 6:01 PM Randy Dunlap <rdunlap@infradead.org> wrote:
> > > > On 11/12/21 4:34 AM, Andy Shevchenko wrote:
> > > 
> > > ...
> > > 
> > > > > + * @rinfo: I²C GPIO recovery information
> > > > 
> > > > Preferably:   "I2C"
> > > 
> > > Why?
> > 
> > See below vvvvvvvvvvvvvvvvv:
> > > > like it is in thousands of places in the kernel source tree.
> > 
> > 
> > > UTF-8 has been established for more than a decade. I prefer to use the
> > > proper form of the abbreviation (*).
> > > 
> > > *) Check UM10204.pdf.
> 
> 
> > > Yes, I am aware of what is in the spec.
> > 
> > Wolfram, what do you prefer?
> 
> > I prefer I2C. But it is more a reading habit. I would neither enforce
> > I2C nor I²C.
> 
> OK, let's leave it as Andy sent it then.
> 
> Acked-by: Randy Dunlap <rdunla@infradead.org>

Thanks!
Wolfram, can it be applied now or should I resend?

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v1 1/1] i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 832 bytes --]

On Fri, Nov 12, 2021 at 02:34:59PM +0200, Andy Shevchenko wrote:
> $ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h
> warning: Function parameter or member 'rst' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'flags' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev'
> warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

Applied to for-next, thanks!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]