[PATCH] mfd: twl-core: Improve the documentation

[PATCH] mfd: twl-core: Improve the documentation

[Dan Carpenter]

Saying it "returns the result" seems tautological.  The read function
does not return num_bytes on success, it returns zero on success.  I
noticed this discrepancy because some of the callers were checking for
>= 0.

Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>

diff --git a/drivers/mfd/twl-core.c b/drivers/mfd/twl-core.c
index c64615dca2bd..07d168f8cc81 100644
--- a/drivers/mfd/twl-core.c
+++ b/drivers/mfd/twl-core.c
@@ -448,7 +448,7 @@ static struct regmap *twl_get_regmap(u8 mod_no)
  * @reg: register address (just offset will do)
  * @num_bytes: number of bytes to transfer
  *
- * Returns the result of operation - 0 is success
+ * Returns 0 on success or else a negative error code.
  */
 int twl_i2c_write(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
 {
@@ -476,7 +476,7 @@ EXPORT_SYMBOL(twl_i2c_write);
  * @reg: register address (just offset will do)
  * @num_bytes: number of bytes to transfer
  *
- * Returns result of operation - num_bytes is success else failure.
+ * Returns 0 on success or else a negative error code.
  */
 int twl_i2c_read(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
 {

[PATCH] mfd: twl-core: Improve the documentation

[Dan Carpenter]

Saying it "returns the result" seems tautological.  The read function
does not return num_bytes on success, it returns zero on success.  I
noticed this discrepancy because some of the callers were checking for
>= 0.

Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>

diff --git a/drivers/mfd/twl-core.c b/drivers/mfd/twl-core.c
index c64615dca2bd..07d168f8cc81 100644
--- a/drivers/mfd/twl-core.c
+++ b/drivers/mfd/twl-core.c
@@ -448,7 +448,7 @@ static struct regmap *twl_get_regmap(u8 mod_no)
  * @reg: register address (just offset will do)
  * @num_bytes: number of bytes to transfer
  *
- * Returns the result of operation - 0 is success
+ * Returns 0 on success or else a negative error code.
  */
 int twl_i2c_write(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
 {
@@ -476,7 +476,7 @@ EXPORT_SYMBOL(twl_i2c_write);
  * @reg: register address (just offset will do)
  * @num_bytes: number of bytes to transfer
  *
- * Returns result of operation - num_bytes is success else failure.
+ * Returns 0 on success or else a negative error code.
  */
 int twl_i2c_read(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
 {

Re: [PATCH] mfd: twl-core: Improve the documentation

[Lee Jones]

On Fri, 30 Jun 2017, Dan Carpenter wrote:

> Saying it "returns the result" seems tautological.  The read function
> does not return num_bytes on success, it returns zero on success.  I
> noticed this discrepancy because some of the callers were checking for
> >= 0.
> 
> Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>

Applied, thanks.

> diff --git a/drivers/mfd/twl-core.c b/drivers/mfd/twl-core.c
> index c64615dca2bd..07d168f8cc81 100644
> --- a/drivers/mfd/twl-core.c
> +++ b/drivers/mfd/twl-core.c
> @@ -448,7 +448,7 @@ static struct regmap *twl_get_regmap(u8 mod_no)
>   * @reg: register address (just offset will do)
>   * @num_bytes: number of bytes to transfer
>   *
> - * Returns the result of operation - 0 is success
> + * Returns 0 on success or else a negative error code.
>   */
>  int twl_i2c_write(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
>  {
> @@ -476,7 +476,7 @@ EXPORT_SYMBOL(twl_i2c_write);
>   * @reg: register address (just offset will do)
>   * @num_bytes: number of bytes to transfer
>   *
> - * Returns result of operation - num_bytes is success else failure.
> + * Returns 0 on success or else a negative error code.
>   */
>  int twl_i2c_read(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
>  {

-- 
Lee Jones
Linaro STMicroelectronics Landing Team Lead
Linaro.org │ Open source software for ARM SoCs
Follow Linaro: Facebook | Twitter | Blog
--
To unsubscribe from this list: send the line "unsubscribe kernel-janitors" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] mfd: twl-core: Improve the documentation

[Lee Jones]

On Fri, 30 Jun 2017, Dan Carpenter wrote:

> Saying it "returns the result" seems tautological.  The read function
> does not return num_bytes on success, it returns zero on success.  I
> noticed this discrepancy because some of the callers were checking for
> >= 0.
> 
> Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>

Applied, thanks.

> diff --git a/drivers/mfd/twl-core.c b/drivers/mfd/twl-core.c
> index c64615dca2bd..07d168f8cc81 100644
> --- a/drivers/mfd/twl-core.c
> +++ b/drivers/mfd/twl-core.c
> @@ -448,7 +448,7 @@ static struct regmap *twl_get_regmap(u8 mod_no)
>   * @reg: register address (just offset will do)
>   * @num_bytes: number of bytes to transfer
>   *
> - * Returns the result of operation - 0 is success
> + * Returns 0 on success or else a negative error code.
>   */
>  int twl_i2c_write(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
>  {
> @@ -476,7 +476,7 @@ EXPORT_SYMBOL(twl_i2c_write);
>   * @reg: register address (just offset will do)
>   * @num_bytes: number of bytes to transfer
>   *
> - * Returns result of operation - num_bytes is success else failure.
> + * Returns 0 on success or else a negative error code.
>   */
>  int twl_i2c_read(u8 mod_no, u8 *value, u8 reg, unsigned num_bytes)
>  {

-- 
Lee Jones
Linaro STMicroelectronics Landing Team Lead
Linaro.org │ Open source software for ARM SoCs
Follow Linaro: Facebook | Twitter | Blog