Skip to content

get rid of the remaining kernel-doc warnings when building the docs

Mauro Carvalho Chehab linux-doc lkml 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest14 patches 5 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/14locking/refcount: document the new "oldp" pointer valueinclude/linux/refcount.h+7 -00 replies
2/14usb: docs: document altmode register/unregister functionsDocumentation/driver-api/usb/typec_bus.rst include/linux/usb/typec_altmode.h+23 -10 replies
3/14XArray: docs: add missing kernel-doc parameters for xas_split_alloc()lib/xarray.c+9 -22 replies
4/14blk-mq: docs: add kernel-doc description for a new struct memberinclude/linux/blk-mq.h+2 -00 replies
5/14iio: docs: add description for a new function memberdrivers/iio/industrialio-core.c+2 -00 replies
6/14nl80211: docs: add a description for s1g_cap parameterinclude/net/cfg80211.h+1 -00 replies
7/14IB/srpt: docs: add a description for cq_size memberdrivers/infiniband/ulp/srpt/ib_srpt.h+1 -00 replies
8/14rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpukernel/rcu/tree.c+6 -80 replies
9/14Input: sparse-keymap: add a description for @swinclude/linux/input/sparse-keymap.h+1 -00 replies
10/14drm: amdgpu: kernel-doc: update some adev parametersdrivers/gpu/drm/amd/amdgpu/amdgpu_device.c drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c+6 -70 replies
11/14drm/amd/display: kernel-doc: document force_timing_syncdrivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h+2 -00 replies
12/14drm: kernel-doc: document drm_dp_set_subconnector_property() paramsdrivers/gpu/drm/drm_dp_helper.c+6 -10 replies
13/14drm: kernel-doc: drm_dp_helper.h: fix a typoinclude/drm/drm_dp_helper.h+1 -10 replies
14/14gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markupsDocumentation/gpu/amdgpu.rst+0 -70 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [PATCH 00/14] get rid of the remaining kernel-doc warnings when building the docs

As described on its subject, this series finally get rid of all kernel-doc warnings.

With this series applied (plus my last series fixing other warnings), building the docs is now clean[1] against next-20200909:

    $ make cleandocs >/dev/null 2>/dev/null && make htmldocs
    Warning: Documentation/bpf/ringbuf.rst references a file that doesn't exist: Documentation/litmus_tests/bpf-rb/_
    rm -f   /devel/v4l/docs/Documentation/output/audio.h.rst /devel/v4l/docs/Documentation/output/ca.h.rst /devel/v4l/docs/Documentation/output/dmx.h.rst /devel/v4l/docs/Documentation/output/frontend.h.rst /devel/v4l/docs/Documentation/output/net.h.rst /devel/v4l/docs/Documentation/output/video.h.rst /devel/v4l/docs/Documentation/output/videodev2.h.rst /devel/v4l/docs/Documentation/output/media.h.rst /devel/v4l/docs/Documentation/output/cec.h.rst /devel/v4l/docs/Documentation/output/lirc.h.rst 2>/dev/null
    Warning: Documentation/bpf/ringbuf.rst references a file that doesn't exist: Documentation/litmus_tests/bpf-rb/_
      SPHINX  htmldocs --> file:///devel/v4l/docs/Documentation/output
      PARSE   include/uapi/linux/dvb/audio.h
      PARSE   include/uapi/linux/dvb/ca.h
      PARSE   include/uapi/linux/dvb/dmx.h
      PARSE   include/uapi/linux/dvb/frontend.h
      PARSE   include/uapi/linux/dvb/net.h
      PARSE   include/uapi/linux/dvb/video.h
      PARSE   include/uapi/linux/videodev2.h
      PARSE   include/uapi/linux/media.h
      PARSE   include/uapi/linux/cec.h
      PARSE   include/uapi/linux/lirc.h
    Running Sphinx v2.4.4
    enabling CJK for LaTeX builder
    building [mo]: targets for 0 po files that are out of date
    building [html]: targets for 2672 source files that are out of date
    updating environment: [new config] 2672 added, 0 changed, 0 removed
    reading sources... [100%] x86/kernel-stacks .. xtensa/mmu                                                                                                                                     
    waiting for workers...
    /devel/v4l/docs/Documentation/bpf/ringbuf.rst:197: WARNING: Unknown target name: "bench_ringbuf.c".
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] w1/w1-netlink .. xtensa/mmu                                                                                                                                          
    waiting for workers...
    generating indices...  genindexdone
    writing additional pages...  searchdone
    copying images... [100%] userspace-api/media/v4l/constraints.svg                                                                                                                              
    copying static files... ... done
    copying extra files... done
    dumping search index in English (code: en)... done
    dumping object inventory... done
    build succeeded, 1 warning.

The HTML pages are in Documentation/output.

At least part of those patches won't apply against docs-next, as they depend on stuff at linux-next. So, it is preferred if they can be applied via each sub-maintainer's tree.

I'll rebase those during the next merge window. This way, if some patches ended being missed, they can be applied by the end of the merge window.

Hopefully, we can make Kernel 5.10 free of documentation warnings.

[1] with the exception of two latmus warnings that seems to require a patch that it was not merged yet.

Regards,
Mauro

Mauro Carvalho Chehab (14):
locking/refcount: document the new "oldp" pointer value
usb: docs: document altmode register/unregister functions
XArray: docs: add missing kernel-doc parameters for xas_split_alloc()
blk-mq: docs: add kernel-doc description for a new struct member
iio: docs: add description for a new function member
nl80211: docs: add a description for s1g_cap parameter IB/srpt: docs: add a description for cq_size member rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu
Input: sparse-keymap: add a description for @sw
drm: amdgpu: kernel-doc: update some adev parameters drm/amd/display: kernel-doc: document force_timing_sync
drm: kernel-doc: document drm_dp_set_subconnector_property() params
drm: kernel-doc: drm_dp_helper.h: fix a typo
gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups

 Documentation/driver-api/usb/typec_bus.rst       |  8 +++++++-
 Documentation/gpu/amdgpu.rst                     |  7 -------
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c       |  2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c      |  6 +++---
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c     |  5 ++---
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h    |  2 ++
 drivers/gpu/drm/drm_dp_helper.c                  |  7 ++++++-
 drivers/iio/industrialio-core.c                  |  2 ++
 drivers/infiniband/ulp/srpt/ib_srpt.h            |  1 +
 include/drm/drm_dp_helper.h                      |  2 +-
 include/linux/blk-mq.h                           |  2 ++
 include/linux/input/sparse-keymap.h              |  1 +
 include/linux/refcount.h                         |  7 +++++++
 include/linux/usb/typec_altmode.h                | 16 ++++++++++++++++
 include/net/cfg80211.h                           |  1 +
 kernel/rcu/tree.c                                | 14 ++++++--------
 lib/xarray.c                                     | 11 +++++++++--
 17 files changed, 67 insertions(+), 27 deletions(-)
Signature · 1 line
2.26.2