[GIT PULL] Docs-build warning fixes for 5.10-rc3

[GIT PULL] Docs-build warning fixes for 5.10-rc3

[Jonathan Corbet]

The following changes since commit
e051955977b7e26124aa8c8398278145f85f94e8:

  documentation: arm: sunxi: add Allwinner H6 documents (2020-10-28 11:19:24 -0600)

are available in the Git repository at:

  git://git.lwn.net/linux.git docs-5.10-warnings

for you to fetch changes up to 6fee9372e0af63f557ad234663d8248f3caefc37:

  Merge branch 'mauro-warnings' into docs-next (2020-10-28 11:42:55 -0600)

----------------------------------------------------------------
This pull contains a series of warning fixes from Mauro; once applied, the
number of warnings from the once-noisy docs build process is nearly zero.
Getting to this point has required a lot of work; once there, hopefully we
can keep things that way.

I have packaged this as a separate pull because it does a fair amount of
reaching outside of Documentation/.  The changes are all in comments and in
code placement.  It's all been in linux-next since last week.

----------------------------------------------------------------
Jonathan Corbet (1):
      Merge branch 'mauro-warnings' into docs-next

Mauro Carvalho Chehab (24):
      scripts: kernel-doc: use :c:union when needed
      sphinx: conf.py: properly handle Sphinx 4.0
      docs: hwmon: adm1266.rst: fix a broken reference
      docs: admin-guide: net.rst: add a missing blank line
      docs: kasan.rst: add two missing blank lines
      docs: net: statistics.rst: remove a duplicated kernel-doc
      docs: hwmon: mp2975.rst: address some html build warnings
      docs: userspace-api: add iommu.rst to the index file
      blk-mq: docs: add kernel-doc description for a new struct member
      mm: pagemap.h: fix two kernel-doc markups
      net: phy: remove kernel-doc duplication
      crypto: sun8x-ce*: update entries to its documentation
      ice: docs fix a devlink info that broke a table
      MAINTAINERS: fix broken doc refs due to yaml conversion
      docs: lockdep-design: fix some warning issues
      locking/refcount: move kernel-doc markups to the proper place
      IB/srpt: docs: add a description for cq_size member
      docs: fs: api-summary.rst: get rid of kernel-doc include
      drm: amdgpu: kernel-doc: update some adev parameters
      gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
      drm: amdgpu_dm: fix a typo
      selftests: kselftest_harness.h: fix kernel-doc markups
      amdgpu: fix a few kernel-doc markup issues
      docs: SafeSetID: fix a warning

 Documentation/admin-guide/LSM/SafeSetID.rst        |   2 +-
 Documentation/admin-guide/sysctl/net.rst           |   1 +
 Documentation/conf.py                              |   2 +-
 Documentation/dev-tools/kasan.rst                  |   2 +
 .../devicetree/bindings/clock/hi6220-clock.txt     |   2 +-
 Documentation/filesystems/api-summary.rst          |   3 -
 Documentation/gpu/amdgpu.rst                       |   7 --
 Documentation/hwmon/adm1266.rst                    |   2 +-
 Documentation/hwmon/index.rst                      |   1 +
 Documentation/hwmon/mp2975.rst                     |  14 ++-
 Documentation/locking/lockdep-design.rst           |  51 ++++----
 Documentation/networking/devlink/ice.rst           |   1 +
 Documentation/networking/statistics.rst            |   3 +-
 Documentation/userspace-api/index.rst              |   1 +
 MAINTAINERS                                        |   9 +-
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-hash.c  |   2 +-
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-prng.c  |   2 +-
 drivers/crypto/allwinner/sun8i-ce/sun8i-ce-trng.c  |   2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c         |  36 +++---
 drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c        |   6 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c       |   7 +-
 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c  |   2 +-
 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h  |   6 +-
 drivers/infiniband/ulp/srpt/ib_srpt.h              |   1 +
 .../bindings/net/wireless/silabs,wfx.yaml          |   2 +-
 include/linux/blk-mq.h                             |   2 +
 include/linux/pagemap.h                            |   8 +-
 include/linux/phy.h                                |  40 +------
 include/linux/refcount.h                           | 130 ++++++++++-----------
 scripts/kernel-doc                                 |   6 +-
 tools/testing/selftests/kselftest_harness.h        |  44 +++----
 31 files changed, 196 insertions(+), 201 deletions(-)

Re: [GIT PULL] Docs-build warning fixes for 5.10-rc3

[Linus Torvalds]

On Tue, Nov 3, 2020 at 11:44 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> This pull contains a series of warning fixes from Mauro; once applied, the
> number of warnings from the once-noisy docs build process is nearly zero.
> Getting to this point has required a lot of work; once there, hopefully we
> can keep things that way.

I wonder if it is quiet enough that we could make new doc build noise
trigger some kind of linux-next warning?

I know Stephen was at least looking at doc build warnings justding by
the thread a couple of weeks ago.

             Linus

Re: [GIT PULL] Docs-build warning fixes for 5.10-rc3

[Matthew Wilcox]

On Tue, Nov 03, 2020 at 01:18:27PM -0800, Linus Torvalds wrote:
> On Tue, Nov 3, 2020 at 11:44 AM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > This pull contains a series of warning fixes from Mauro; once applied, the
> > number of warnings from the once-noisy docs build process is nearly zero.
> > Getting to this point has required a lot of work; once there, hopefully we
> > can keep things that way.
> 
> I wonder if it is quiet enough that we could make new doc build noise
> trigger some kind of linux-next warning?

We can move checkdoc out of W=1 ... something like this?

+++ b/scripts/Makefile.build
@@ -103,9 +103,7 @@ else ifeq ($(KBUILD_CHECKSRC),2)
         cmd_force_checksrc = $(CHECK) $(CHECKFLAGS) $(c_flags) $<
 endif
 
-ifneq ($(KBUILD_EXTRA_WARN),)
-  cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $<
-endif
+cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $<
 
 # Compile C sources (.c)
 # ---------------------------------------------------------------------------

although people might whinge if it increases kernel build time noticably
(I haven't checked if it does).

It won't catch all the things that actually running Sphinx will, but
it catches the common things (forgot to update the docs after changing a
function parameter, for example)

Re: [GIT PULL] Docs-build warning fixes for 5.10-rc3

[pr-tracker-bot]

The pull request you sent on Tue, 3 Nov 2020 12:44:20 -0700:

> git://git.lwn.net/linux.git docs-5.10-warnings

has been merged into torvalds/linux.git:
https://git.kernel.org/torvalds/c/e6b0bd61a73718886c2df16762f0a5dba485fc10

Thank you!

-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/prtracker.html

Re: [GIT PULL] Docs-build warning fixes for 5.10-rc3

[Stephen Rothwell]

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

Hi Linus,

On Tue, 3 Nov 2020 13:18:27 -0800 Linus Torvalds <torvalds@linux-foundation.org> wrote:
>
> On Tue, Nov 3, 2020 at 11:44 AM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > This pull contains a series of warning fixes from Mauro; once applied, the
> > number of warnings from the once-noisy docs build process is nearly zero.
> > Getting to this point has required a lot of work; once there, hopefully we
> > can keep things that way.  
> 
> I wonder if it is quiet enough that we could make new doc build noise
> trigger some kind of linux-next warning?
> 
> I know Stephen was at least looking at doc build warnings justding by
> the thread a couple of weeks ago.

What I am currently doing is a "make htmldocs" on your tree and then again
on the whole linux-next release and reporting changes.

There is currently one message produced in your tree (after I add all
the "pending fixes") and I have reported that this morning.  So things
are looking pretty good now - a lot of good work over the past couple
of releases.

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [GIT PULL] Docs-build warning fixes for 5.10-rc3

[Jonathan Corbet]

On Thu, 5 Nov 2020 09:06:52 +1100
Stephen Rothwell <sfr@canb.auug.org.au> wrote:

> There is currently one message produced in your tree (after I add all
> the "pending fixes") and I have reported that this morning.  So things
> are looking pretty good now - a lot of good work over the past couple
> of releases.

The credit for that really belongs to Mauro.  Much appreciated!

jon