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

Mauro Carvalho Chehab
2020-09-10T10:26:51Z

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(-)

--
2.26.2