[PATCH 00/17] Address several documentation build warnings

[PATCH 00/17] Address several documentation build warnings

[Mauro Carvalho Chehab]

This patch series is against next-20200317. It addresses several warnings on
random places.

It is worth noticing patch 07/17: It changes kernel-doc parser to accept a
very common pattern on kernel-doc markups. This reduces a lot of
warnings all over the tree.

The remaining patches are just random fixes with the hope to address most
warnings that are shown in red when building the documentation.

Mauro Carvalho Chehab (17):
  docs: amu: supress some Sphinx warnings
  docs: arm64: booting.rst: get rid of some warnings
  docs: pci: boot-interrupts.rst: improve html output
  kernel: futex.c: get rid of a docs build warning
  devfreq: devfreq.h: get rid of some doc warnings
  firewire: firewire-cdev.hL get rid of a docs warning
  scripts: kernel-doc: proper handle @foo->bar()
  lib: bitmap.c: get rid of some doc warnings
  rcu: update.c: get rid of some doc warnings
  net: phy: sfp-bus.c: get rid of docs warnings
  net: core: dev.c: fix a documentation warning
  gpio: gpiolib.c: fix a doc warning
  i2c: include/linux/i2c.h: fix a doc warning
  infiniband: pa_vnic_encap.h: get rid of a warning
  ata: libata-core: fix a doc warning
  fs: inode.c: get rid of docs warnings
  regulator: driver.h: fix regulator_map_* function names

 Documentation/PCI/boot-interrupts.rst         | 34 ++++++++++--------
 Documentation/arm64/amu.rst                   |  5 +++
 Documentation/arm64/booting.rst               | 36 +++++++++++--------
 drivers/ata/libata-core.c                     |  2 +-
 drivers/gpio/gpiolib.c                        |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 drivers/net/phy/sfp-bus.c                     | 32 +++++++++--------
 fs/inode.c                                    |  6 ++--
 include/linux/devfreq.h                       |  6 ++--
 include/linux/i2c.h                           |  4 +--
 include/linux/regulator/driver.h              |  4 +--
 include/uapi/linux/firewire-cdev.h            |  2 +-
 kernel/futex.c                                |  3 +-
 kernel/rcu/update.c                           |  8 ++---
 lib/bitmap.c                                  | 27 +++++++-------
 net/core/dev.c                                |  2 +-
 scripts/kernel-doc                            |  2 ++
 17 files changed, 101 insertions(+), 76 deletions(-)

-- 
2.24.1

[PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Mauro Carvalho Chehab]

Don't let non-letters inside a literal block without escaping it, as
the toolchain would mis-interpret it:

./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/i2c.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index f834687989f7..f6b942150631 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -506,7 +506,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  * @smbus_xfer_atomic: same as @smbus_xfer. Yet, only using atomic context
  *   so e.g. PMICs can be accessed very late before shutdown. Optional.
  * @functionality: Return the flags that this algorithm/adapter pair supports
- *   from the I2C_FUNC_* flags.
+ *   from the ``I2C_FUNC_*`` flags.
  * @reg_slave: Register given client to I2C slave mode of this adapter
  * @unreg_slave: Unregister given client from I2C slave mode of this adapter
  *
@@ -515,7 +515,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  * be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584
  * to name two of the most common.
  *
- * The return codes from the @master_xfer{_atomic} fields should indicate the
+ * The return codes from the ``master_xfer{_atomic}`` fields should indicate the
  * type of error code that occurred during the transfer, as documented in the
  * Kernel Documentation file Documentation/i2c/fault-codes.rst.
  */
-- 
2.24.1

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Wolfram Sang]

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

On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> Don't let non-letters inside a literal block without escaping it, as
> the toolchain would mis-interpret it:
> 
> ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Shall I take this via I2C?

If not:

Acked-by: Wolfram Sang <wsa@the-dreams.de>


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

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Mauro Carvalho Chehab]

Em Tue, 17 Mar 2020 16:03:22 +0100
Wolfram Sang <wsa@the-dreams.de> escreveu:

> On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> > Don't let non-letters inside a literal block without escaping it, as
> > the toolchain would mis-interpret it:
> > 
> > ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Shall I take this via I2C?

Yeah, feel free to pick it. The patches on this series are pretty
much independent from the others.

Thanks,
Mauro

Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning

[Wolfram Sang]

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

On Tue, Mar 17, 2020 at 03:54:22PM +0100, Mauro Carvalho Chehab wrote:
> Don't let non-letters inside a literal block without escaping it, as
> the toolchain would mis-interpret it:
> 
> ./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied to for-current, thanks!


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