get rid of the remaining kernel-doc warnings when building the docs
Subsystems (17)
PATCH 5/14 iio: docs: add description for a new function member
In reply to Mauro Carvalho ChehabChangeset 78289b4a58b5 ("iio: core: pass parent device as parameter during allocation")
added a new parameter to the allocation function, but didn't
add the corresponding kernel-doc markup, as reported:
./drivers/iio/industrialio-core.c:1531: warning: Function parameter or member 'parent' not described in 'iio_device_alloc'
Copy the parameter description for the devm_ variant.
--- drivers/iio/industrialio-core.c | 2 ++ 1 file changed, 2 insertions(+)
drivers/iio/industrialio-core.c +2 -0
@@ -1524,6 +1524,8 @@ struct device_type iio_device_type = {/** * iio_device_alloc() - allocate an iio_dev from a driver +* @parent: Device to allocate iio_dev for, and parent for +* this IIO device * @sizeof_priv: Space to allocate for private structure. **/ struct iio_dev *iio_device_alloc (struct device *parent,int sizeof_priv)
Signature · 1 line
2.26.2
PATCH 1/14 locking/refcount: document the new "oldp" pointer value
In reply to Mauro Carvalho ChehabChangeset a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value") added a new parameter to most refcount functions, but didn't update
the kernel-doc markups.
Add a description for it on all touched functions.
--- include/linux/refcount.h | 7 +++++++ 1 file changed, 7 insertions(+)
include/linux/refcount.h +7 -0
@@ -151,6 +151,7 @@ static inline unsigned int refcount_read(const refcount_t *r)* refcount_add_not_zero - add a value to a refcount unless it is 0 * @i: the value to add to the refcount * @r: the refcount +* @oldp: if not NULL, stores the previous value of the refcount * * Will saturate at REFCOUNT_SATURATED and WARN. *
@@ -192,6 +193,7 @@ static inline __must_check bool refcount_add_not_zero(int i, refcount_t *r)* refcount_add - add a value to a refcount * @i: the value to add to the refcount * @r: the refcount +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_add(), but will saturate at REFCOUNT_SATURATED and WARN. *
@@ -225,6 +227,7 @@ static inline void refcount_add(int i, refcount_t *r)/** * refcount_inc_not_zero - increment a refcount unless it is 0 * @r: the refcount to increment +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_inc_not_zero(), but will saturate at REFCOUNT_SATURATED * and WARN.
@@ -248,6 +251,7 @@ static inline __must_check bool refcount_inc_not_zero(refcount_t *r)/** * refcount_inc - increment a refcount * @r: the refcount to increment +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_inc(), but will saturate at REFCOUNT_SATURATED and WARN. *
@@ -271,6 +275,7 @@ static inline void refcount_inc(refcount_t *r)* refcount_sub_and_test - subtract from a refcount and test if it is 0 * @i: amount to subtract from the refcount * @r: the refcount +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_dec_and_test(), but it will WARN, return false and * ultimately leak on underflow and will fail to decrement when saturated
@@ -313,6 +318,7 @@ static inline __must_check bool refcount_sub_and_test(int i, refcount_t *r)/** * refcount_dec_and_test - decrement a refcount and test if it is 0 * @r: the refcount +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_dec_and_test(), it will WARN on underflow and fail to * decrement when saturated at REFCOUNT_SATURATED.
@@ -336,6 +342,7 @@ static inline __must_check bool refcount_dec_and_test(refcount_t *r)/** * refcount_dec - decrement a refcount * @r: the refcount +* @oldp: if not NULL, stores the previous value of the refcount * * Similar to atomic_dec(), it will WARN on underflow and fail to decrement * when saturated at REFCOUNT_SATURATED.
Signature · 1 line
2.26.2
PATCH 3/14 XArray: docs: add missing kernel-doc parameters for xas_split_alloc()
In reply to Mauro Carvalho ChehabThe parameters for such function are not described. Copy the description from the conventions (at the beginning of this file), and fill in the blanks for the @order parameter.
--- lib/xarray.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
lib/xarray.c +9 -2
@@ -1004,8 +1004,15 @@ static void node_set_marks(struct xa_node *node, unsigned int offset, }/** -* Allocate memory for splitting an entry of @order size into the order -* stored in the @xas. +* xas_split_alloc() - Allocate memory for splitting an entry of +* @order size into the order stored in the @xas. +* +* @xas: is the 'xarray operation state'. It may be either a pointer to +* an xa_state, or an xa_state stored on the stack. This is an unfortunate +* ambiguity. +* @entry: refers to something stored in a slot in the xarray +* @order: size of each entry +* @gfp: GFP allocation flags */ void xas_split_alloc (struct xa_state *xas,void *entry,unsigned int order,gfp_t gfp)
Signature · 1 line
2.26.2
PATCH 11/14 drm/amd/display: kernel-doc: document force_timing_sync
In reply to Mauro Carvalho ChehabAs warned when running "make htmldocs":
./drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:345: warning: Function parameter or member 'force_timing_sync' not described in 'amdgpu_display_manager'
This new struct member was not documented at kernel-doc markup.
--- drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 2 ++ 1 file changed, 2 insertions(+)
drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h +2 -0
@@ -149,6 +149,8 @@ struct amdgpu_dm_backlight_caps {* @cached_state: Caches device atomic state for suspend/resume * @cached_dc_state: Cached state of content streams * @compressor: Frame buffer compression buffer. See &struct dm_comressor_info +* @force_timing_sync: set via debugfs. When set, indicates that all connected +* displays will be forced to synchronize. */ struct amdgpu_display_manager {
Signature · 1 line
2.26.2
PATCH 8/14 rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu
In reply to Mauro Carvalho ChehabChangeset 53c72b590b3a ("rcu/tree: cache specified number of objects")
added new members for struct kfree_rcu_cpu, but didn't add the
corresponding at the kernel-doc markup, as repoted when doing
"make htmldocs":
./kernel/rcu/tree.c:3113: warning: Function parameter or member 'bkvcache' not described in 'kfree_rcu_cpu' ./kernel/rcu/tree.c:3113: warning: Function parameter or member 'nr_bkv_objs' not described in 'kfree_rcu_cpu'
So, move the description for bkvcache to kernel-doc, and add a description for nr_bkv_objs.
--- kernel/rcu/tree.c | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-)
kernel/rcu/tree.c +6 -8
@@ -3085,6 +3085,12 @@ struct kfree_rcu_cpu_work {* @monitor_todo: Tracks whether a @monitor_work delayed work is pending * @initialized: The @rcu_work fields have been initialized * @count: Number of objects for which GP not started +* @bkvcache: +* A simple cache list that contains objects for reuse purpose. +* In order to save some per-cpu space the list is singular. +* Even though it is lockless an access has to be protected by the +* per-cpu lock. +* @nr_bkv_objs: number of allocated objects at @bkvcache. * * This is a per-CPU structure. The reason that it is not included in * the rcu_data structure is to permit this code to be extracted from
@@ -3100,14 +3106,6 @@ struct kfree_rcu_cpu {bool monitor_todo;bool initialized;int count; - -/* -* A simple cache list that contains objects for -* reuse purpose. In order to save some per-cpu -* space the list is singular. Even though it is -* lockless an access has to be protected by the -* per-cpu lock. -*/ struct llist_head bkvcache;int nr_bkv_objs; };
Signature · 1 line
2.26.2
PATCH 13/14 drm: kernel-doc: drm_dp_helper.h: fix a typo
In reply to Mauro Carvalho ChehabRight now, kernel-doc generates a warning:
./include/drm/drm_dp_helper.h:1786: warning: Function parameter or member 'hbr2_reset' not described in 'drm_dp_phy_test_params'
This is due to a typo:
@hb2_reset -> @hbr2_reset
--- include/drm/drm_dp_helper.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/drm/drm_dp_helper.h +1 -1
@@ -1771,7 +1771,7 @@ static inline void drm_dp_cec_unset_edid(struct drm_dp_aux *aux)* @link_rate: Requested Link rate from DPCD 0x219 * @num_lanes: Number of lanes requested by sing through DPCD 0x220 * @phy_pattern: DP Phy test pattern from DPCD 0x248 -* @hb2_reset: DP HBR2_COMPLIANCE_SCRAMBLER_RESET from DCPD 0x24A and 0x24B +* @hbr2_reset: DP HBR2_COMPLIANCE_SCRAMBLER_RESET from DCPD 0x24A and 0x24B * @custom80: DP Test_80BIT_CUSTOM_PATTERN from DPCDs 0x250 through 0x259 * @enhanced_frame_cap: flag for enhanced frame capability. */
Signature · 1 line
2.26.2
PATCH 14/14 gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
In reply to Mauro Carvalho ChehabAs reported by kernel-doc:
./drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c:1: warning: no structured comments found ./drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c:1: warning: no structured comments found
Those files only contain
/** * DOC: */
markups, but they're included twice there: one to parse such markup, and another one to parse internal functions.
In the case of amdgpu_xgmi.c, as it has just one such markup, we can simply include the file once, and let it parse the entire file without passing arguments to kernel-doc.
This should place everything altogether.
For amdgpu_ras.c, however, we need to remove the kernel-doc with just internal. This should be re-introduced if this file ever gets new non-DOC markups.
--- Documentation/gpu/amdgpu.rst | 7 ------- 1 file changed, 7 deletions(-)
Documentation/gpu/amdgpu.rst +0 -7
@@ -74,10 +74,6 @@ AMDGPU XGMI Support =================== .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c - :doc: AMDGPU XGMI Support - -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c - :internal: AMDGPU RAS Support ==================
@@ -115,9 +111,6 @@ RAS VRAM Bad Pages sysfs Interface .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c - :internal: - Sample Code ----------- Sample code for testing error injection can be found here:
Signature · 1 line
2.26.2
PATCH 4/14 blk-mq: docs: add kernel-doc description for a new struct member
In reply to Mauro Carvalho ChehabAs reported by kernel-doc:
./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
There is now a new member for struct blk_mq_tag_set. Add a description for it, based on the commit that introduced it.
--- include/linux/blk-mq.h | 2 ++ 1 file changed, 2 insertions(+)
include/linux/blk-mq.h +2 -0
@@ -235,6 +235,8 @@ enum hctx_type {* @flags: Zero or more BLK_MQ_F_* flags. * @driver_data: Pointer to data owned by the block driver that created this * tag set. +* @active_queues_shared_sbitmap: +* number of active request queues per tag set. * @__bitmap_tags: A shared tags sbitmap, used over all hctx's * @__breserved_tags: * A shared reserved tags sbitmap, used over all hctx's
Signature · 1 line
2.26.2
PATCH 7/14 IB/srpt: docs: add a description for cq_size member
In reply to Mauro Carvalho ChehabChangeset c804af2c1d31 ("IB/srpt: use new shared CQ mechanism")
added a new member for struct srpt_rdma_ch, but didn't add the
corresponding kernel-doc markup, as repoted when doing
"make htmldocs":
./drivers/infiniband/ulp/srpt/ib_srpt.h:331: warning: Function parameter or member 'cq_size' not described in 'srpt_rdma_ch'
Add a description for it.
--- drivers/infiniband/ulp/srpt/ib_srpt.h | 1 + 1 file changed, 1 insertion(+)
drivers/infiniband/ulp/srpt/ib_srpt.h +1 -0
@@ -256,6 +256,7 @@ enum rdma_ch_state {* @rdma_cm: See below. * @rdma_cm.cm_id: RDMA CM ID associated with the channel. * @cq: IB completion queue for this channel. +* @cq_size: Size of the @cq pool. * @zw_cqe: Zero-length write CQE. * @rcu: RCU head. * @kref: kref for this channel.
Signature · 1 line
2.26.2
cover 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
PATCH 2/14 usb: docs: document altmode register/unregister functions
The typec_bus.rst asks for documentation of those two functions, but they don't exist:
./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found ./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_register_driver' not found
Also, they're not declared on bus.c but, instead, at a header file (typec_altmode.h).
So, add documentation for both functions at the header and change the kernel-doc markup under typec_bus.rst to point to the right place.
While here, also place the documentation for both structs declared on typec_altmode.h at the rst file.
--- Documentation/driver-api/usb/typec_bus.rst | 8 +++++++- include/linux/usb/typec_altmode.h | 16 ++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-)
Documentation/driver-api/usb/typec_bus.rst +7 -1
@@ -91,10 +91,16 @@ their control. Driver API ---------- +Alternate mode structs +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/usb/typec_altmode.h + :functions: typec_altmode_driver typec_altmode_ops + Alternate mode driver registering/unregistering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/usb/typec/bus.c +.. kernel-doc:: include/linux/usb/typec_altmode.h :functions: typec_altmode_register_driver typec_altmode_unregister_driver Alternate mode driver operations
include/linux/usb/typec_altmode.h +16 -0
@@ -152,10 +152,26 @@ struct typec_altmode_driver {#define to_altmode_driver (d) container_of(d, struct typec_altmode_driver, \ driver) +/** +* typec_altmode_register_driver - registers a USB Type-C alternate mode +* device driver +* @drv: pointer to struct typec_altmode_driver +* +* These drivers will be bind to the partner alternate mode devices. They will +* handle all SVID specific communication. +*/ #define typec_altmode_register_driver (drv) \ __typec_altmode_register_driver(drv, THIS_MODULE)int __typec_altmode_register_driver (struct typec_altmode_driver *drv,struct module *module); +/** +* typec_altmode_unregister_driver - unregisters a USB Type-C alternate mode +* device driver +* @drv: pointer to struct typec_altmode_driver +* +* These drivers will be bind to the partner alternate mode devices. They will +* handle all SVID specific communication. +*/ void typec_altmode_unregister_driver (struct typec_altmode_driver *drv);#define module_typec_altmode_driver (__typec_altmode_driver) \
Signature · 1 line
2.26.2
PATCH 9/14 Input: sparse-keymap: add a description for @sw
In reply to Mauro Carvalho ChehabAdd a description for it, in order to avoids this warning:
./include/linux/input/sparse-keymap.h:43: warning: Function parameter or member 'sw' not described in 'key_entry'
--- include/linux/input/sparse-keymap.h | 1 + 1 file changed, 1 insertion(+)
include/linux/input/sparse-keymap.h +1 -0
@@ -20,6 +20,7 @@* private definitions. * @code: Device-specific data identifying the button/switch * @keycode: KEY_* code assigned to a key/button +* @sw: struct with code/value used by KE_SW and KE_VSW * @sw.code: SW_* code assigned to a switch * @sw.value: Value that should be sent in an input even when KE_SW * switch is toggled. KE_VSW switches ignore this field and
Signature · 1 line
2.26.2
PATCH 12/14 drm: kernel-doc: document drm_dp_set_subconnector_property() params
In reply to Mauro Carvalho ChehabChangeset e5b92773287c ("drm: report dp downstream port type as a subconnector property") added a new function to the kAPI, but didn't add any documentation
for the parameters for drm_dp_set_subconnector_property().
--- drivers/gpu/drm/drm_dp_helper.c | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
drivers/gpu/drm/drm_dp_helper.c +6 -1
@@ -599,7 +599,8 @@ EXPORT_SYMBOL(drm_dp_downstream_debug);/** * drm_dp_subconnector_type() - get DP branch device type -* +* @dpcd: DisplayPort configuration data +* @port_cap: port capabilities */ enum drm_mode_subconnector drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
@@ -650,6 +651,10 @@ EXPORT_SYMBOL(drm_dp_subconnector_type);/** * drm_mode_set_dp_subconnector_property - set subconnector for DP connector +* @connector: connector to set property on +* @status: connector status +* @dpcd: DisplayPort configuration data +* @port_cap: port capabilities * * Called by a driver on every detect event. */
Signature · 1 line
2.26.2
PATCH 6/14 nl80211: docs: add a description for s1g_cap parameter
In reply to Mauro Carvalho ChehabChangeset df78a0c0b67d ("nl80211: S1G band and channel definitions") added a new parameter, but didn't add the corresponding kernel-doc markup, as repoted when doing "make htmldocs":
./include/net/cfg80211.h:471: warning: Function parameter or member 's1g_cap' not described in 'ieee80211_supported_band'
Add a documentation for it.
--- include/net/cfg80211.h | 1 + 1 file changed, 1 insertion(+)
include/net/cfg80211.h +1 -0
@@ -449,6 +449,7 @@ struct ieee80211_sta_s1g_cap {* @n_bitrates: Number of bitrates in @bitrates * @ht_cap: HT capabilities in this band * @vht_cap: VHT capabilities in this band +* @s1g_cap: S1G capabilities in this band * @edmg_cap: EDMG capabilities in this band * @n_iftype_data: number of iftype data entries * @iftype_data: interface type data entries. Note that the bits in
Signature · 1 line
2.26.2
PATCH 10/14 drm: amdgpu: kernel-doc: update some adev parameters
In reply to Mauro Carvalho ChehabRunning "make htmldocs: produce lots of warnings on those files:
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini' ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init' ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
They're related to the repacement of some parameters by adev, and due to a few renamed parameters.
Update the kernel-doc documentation accordingly.
--- 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 ++--- 3 files changed, 6 insertions(+), 7 deletions(-)
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c +1 -1
@@ -667,7 +667,7 @@ static void amdgpu_block_invalid_wreg(struct amdgpu_device *adev,/** * amdgpu_device_asic_init - Wrapper for atom asic_init * -* @dev: drm_device pointer +* @adev: drm_device pointer * * Does any asic specific work and then calls atom asic init. */
drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c +3 -3
@@ -81,8 +81,8 @@ static const struct ttm_resource_manager_func amdgpu_gtt_mgr_func;/** * amdgpu_gtt_mgr_init - init GTT manager and DRM MM * -* @man: TTM memory type manager -* @p_size: maximum size of GTT +* @adev: amdgpu device structure +* @gtt_size: maximum size of GTT * * Allocate and initialize the GTT manager. */
@@ -125,7 +125,7 @@ int amdgpu_gtt_mgr_init(struct amdgpu_device *adev, uint64_t gtt_size)/** * amdgpu_gtt_mgr_fini - free and destroy GTT manager * -* @man: TTM memory type manager +* @adev: amdgpu device structure * * Destroy and free the GTT manager, returns -EBUSY if ranges are still * allocated inside it.
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c +2 -3
@@ -168,8 +168,7 @@ static const struct ttm_resource_manager_func amdgpu_vram_mgr_func;/** * amdgpu_vram_mgr_init - init VRAM manager and DRM MM * -* @man: TTM memory type manager -* @p_size: maximum size of VRAM +* @adev: amdgpu device structure * * Allocate and initialize the VRAM manager. */
@@ -202,7 +201,7 @@ int amdgpu_vram_mgr_init(struct amdgpu_device *adev)/** * amdgpu_vram_mgr_fini - free and destroy VRAM manager * -* @man: TTM memory type manager +* @adev: amdgpu device structure * * Destroy and free the VRAM manager, returns -EBUSY if ranges are still * allocated inside it.
Signature · 1 line
2.26.2
Matthew Wilcox
maintainerRe: [PATCH 03/14] XArray: docs: add missing kernel-doc parameters for xas_split_alloc()
In reply to Mauro Carvalho ChehabQuoted 5 lines · Mauro Carvalho Chehab
/**
- * Allocate memory for splitting an entry of @order size into the order
- * stored in the @xas.
+ *xas_split_alloc()- Allocate memory for splitting an entry of
+ * @order size into the order stored in the @xas.
Quoted 8 lines
+ *
+ * @xas: is the 'xarray operation state'. It may be either a pointer to
+ * anxa_state, or anxa_statestored on the stack. This is an unfortunate
+ * ambiguity.
+ * @entry: refers to something stored in a slot in the xarray
+ * @order: size of each entry
+ * @gfp: GFP allocation flags
*/
No. I'll do this properly. Sorry for forgetting to document the arguments.
Quoted 5 lines
void xas_split_alloc(struct
xa_state*xas, void *entry, unsigned int order,
gfp_tgfp)Signature · 1 line
2.26.2
Matthew Wilcox
maintainerQuoted 4 lines · Mauro Carvalho Chehab
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:
Thanks, this has been a truly heroic effort.
I'd suggest that we change the kernel build to always run the CHKDOC instead of at W=1 (or rather, as the patch I just sent out demonstrates, not at all (oops)). Otherwise you're just going to have to continue doing this.
At some point, perhaps we can add some other warnings at W=1, like an EXPORT_SYMBOL of a function which doesn't have kernel-doc.
Re: [PATCH 03/14] XArray: docs: add missing kernel-doc parameters for xas_split_alloc()
In reply to Matthew WilcoxEm Thu, 10 Sep 2020 12:13:22 +0100
Matthew Wilcox <[email protected]> escreveu:
Quoted 15 lines · Mauro Carvalho Chehab
Quoted 5 lines
/**
- * Allocate memory for splitting an entry of @order size into the order
- * stored in the @xas.
+ *xas_split_alloc()- Allocate memory for splitting an entry of
+ * @order size into the order stored in the @xas.Quoted 8 lines
+ *
+ * @xas: is the 'xarray operation state'. It may be either a pointer to
+ * anxa_state, or anxa_statestored on the stack. This is an unfortunate
+ * ambiguity.
+ * @entry: refers to something stored in a slot in the xarray
+ * @order: size of each entry
+ * @gfp: GFP allocation flags
*/
Quoted 1 line
No. I'll do this properly.
Thanks! Yeah, you should be able to document it better than me, as I'm not familiar with XArray subsystem ;-)
Quoted 1 line
Sorry for forgetting to document the arguments.
No problem. I know it was hard to identify such warnings in the past, as we used to have hundreds of warnings. Btw, while writing this series that finally gets rid of them, I even identified one such warning on media that slept though my review ;-)
Thanks,
Mauro
Em Thu, 10 Sep 2020 19:12:08 +0100
Matthew Wilcox <[email protected]> escreveu:
Quoted 6 lines · Mauro Carvalho Chehab
Quoted 4 lines
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:
Quoted 6 lines
Thanks, this has been a truly heroic effort.
I'd suggest that we change the kernel build to always run the CHKDOC instead of at W=1 (or rather, as the patch I just sent out demonstrates, not at all (oops)). Otherwise you're just going to have to continue doing this.
It sounds a good idea for me to run kernel-doc with W=1 - or even better - with allyesconfig/allmodconfig (no matter if W=0/W=1/W=2).
Quoted 2 lines
At some point, perhaps we can add some other warnings at W=1, like an
EXPORT_SYMBOLof a function which doesn't have kernel-doc.
Makes sense, but I suspect that supporting it is not too trivial.
I mean, a script checking for EXPORT_SYMBOL* should check not only the C file, but also the included header files, as the kernel-doc markup can be on one of its includes.
An enhanced version of something like this:
</script>
#!/usr/bin/perl
my $file = shift or die "Need a file name";
my @files;
my @exports;
my $dir = $file;
$dir =~ s,[^\/]+$,,;
push @files, $file;
open IN, "<$file";
while (<IN>) {
push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/);
push @files, "include/$1" if (m/^\s*#\s*include\s+[\<](\S+)[\>]/);
push @files, "$dir/$1" if (m/^\s*#\s*include\s+[\"](\S+)[\"]/);
}close IN;
my $doc;
foreach my $i (@files) {
$doc .= qx(./scripts/kernel-doc $i 2>/dev/null);
}foreach my $e (@exports) {
print "$e doesn't have kernel-doc markups\n" if (!($doc =~ m/\b$e\b/));
}</script>
On simple cases, the above script helps to check what's missing:
$ ./check_exports drivers/acpi/acpi_lpat.c <nothing returned> $ ./test drivers/media/v4l2-core/v4l2-common.c __v4l2_find_nearest_size doesn't have kernel-doc markups v4l2_apply_frmsize_constraints doesn't have kernel-doc markups v4l2_fill_pixfmt_mp doesn't have kernel-doc markups v4l2_fill_pixfmt doesn't have kernel-doc markups
Yet, it the actual script will also need to handle some special cases:
- it should check if the Makefile used by the file has a "-I" directive. This could be tricky, due to Makefile recursion.
- it should also check if there is a kernel-doc entry for such header. a "git grep" could be used in this case.
- It should also handle the optional arguments of kernel-doc, like :internal", :external", ":no-identifiers", "identifiers", as it is possible that there is a kernel-doc entry, but this is excluded by a kernel-doc modifier.
- It should also check if the exported symbol is a function, in order to exclude static vars that are exported.
I suspect that there are several other border cases.
Thanks,
Mauro
Em Mon, 5 Oct 2020 12:51:11 +0200
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 71 lines
Em Thu, 10 Sep 2020 19:12:08 +0100
Matthew Wilcox <[email protected]> escreveu:Quoted 6 lines · Mauro Carvalho Chehab
Quoted 4 lines
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:
Quoted 6 lines
Thanks, this has been a truly heroic effort.
I'd suggest that we change the kernel build to always run the CHKDOC instead of at W=1 (or rather, as the patch I just sent out demonstrates, not at all (oops)). Otherwise you're just going to have to continue doing this.
It sounds a good idea for me to run kernel-doc with W=1 - or even better - with allyesconfig/allmodconfig (no matter if W=0/W=1/W=2).
Quoted 2 lines
At some point, perhaps we can add some other warnings at W=1, like an
EXPORT_SYMBOLof a function which doesn't have kernel-doc.Makes sense, but I suspect that supporting it is not too trivial.
I mean, a script checking for EXPORT_SYMBOL* should check not only the C file, but also the included header files, as the kernel-doc markup can be on one of its includes.
An enhanced version of something like this:
</script>
#!/usr/bin/perlmy $file = shift or die "Need a file name";
my @files;
my @exports;my $dir = $file;
$dir =~ s,[^\/]+$,,;push @files, $file;
open IN, "<$file";while (<IN>) { push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/); push @files, "include/$1" if (m/^\s*#\s*include\s+[\<](\S+)[\>]/); push @files, "$dir/$1" if (m/^\s*#\s*include\s+[\"](\S+)[\"]/); }close IN;
my $doc;
foreach my $i (@files) { $doc .= qx(./scripts/kernel-doc $i 2>/dev/null); }foreach my $e (@exports) { print "$e doesn't have kernel-doc markups\n" if (!($doc =~ m/\b$e\b/)); }</script>
On simple cases, the above script helps to check what's missing:
$ ./check_exports drivers/acpi/acpi_lpat.c <nothing returned> $ ./test drivers/media/v4l2-core/v4l2-common.c __v4l2_find_nearest_size doesn't have kernel-doc markups v4l2_apply_frmsize_constraints doesn't have kernel-doc markups v4l2_fill_pixfmt_mp doesn't have kernel-doc markups v4l2_fill_pixfmt doesn't have kernel-doc markups
Quoted 5 lines
Yet, it the actual script will also need to handle some special cases:
- it should check if the
Makefileused by the file has a "-I" directive. This could be tricky, due toMakefilerecursion.
Hmm... actually this could be obtained via command line parameters, if the script is called with the same parameter set as the one passed to the C compiler.
Quoted 9 lines
- it should also check if there is a kernel-doc entry for such header. a "git grep" could be used in this case.
- It should also handle the optional arguments of kernel-doc, like :internal", :external", ":no-identifiers", "identifiers", as it is possible that there is a kernel-doc entry, but this is excluded by a kernel-doc modifier.
- It should also check if the exported symbol is a function, in order to exclude static vars that are exported.
Quoted 4 lines
I suspect that there are several other border cases.
Thanks,
Mauro
Thanks,
Mauro
RFC PATCH 1/1 script: add a script for checking doc problems with external functions
While not all EXPORT_SYMBOL*() symbols should be documented, it seems useful to have a tool which would help to check what symbols aren't documented.
This is a first step on this direction. The tool has some limitations. Yet, it could be useful for maintainers to check about missing documents on their subsystems.
--- scripts/check_docs_external_symbols | 127 ++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100755 scripts/check_docs_external_symbols
scripts/check_docs_external_symbols new file +127 -0
@@ -0,0 +1,127 @@ +#!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 + +# +# Copyright (c) 2020, Huawei Tech. Co., Ltd. +# Author: Mauro Carvalho Chehab <[email protected] +# +# This script helps to check if exported functions are documented at either +# a file, on at the included headers. +# +# The script is not perfect and may produce some false negatives, as +# currently it doesn't handle Makefile "-I" directives that might be inside +# a Kernel directory. +# +# So, use it with caution. +# +# Usage: +# scripts/check_external docs +# or: +# scripts/check_external docs <files and/or directories> + +use warnings; +use strict; +use File::Find; + +sub check_file($) { + my $file = shift; + my (@files, @exports, @doc, @doc_refs); + my $content = "\n"; + + return 0 if (!($file =~ /\.[ch]$/)); + + my $dir = $file; + $dir =~ s,[^\/]+$,,; + + open IN, $file or return 0; + while (<IN>) { + push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/); + + if (m/^\s*#\s*include\s+[\<](\S+)[\>]/) { + if (-e "include/$1") { + push @files, "include/$1"; + } else { + # Currently, can't check if include is elsewhere + return 0; + } + } + if (m/^\s*#\s*include\s+[\"](\S+)[\"]/) { + if (-e "$dir/$1") { + push @files, "$dir/$1"; + } else { + # Currently, can't check if include is elsewhere + return 0; + } + } + $content .= $_; + } + close IN; + + return 0 if ($content eq "\n"); + + + push @files, $file; + for (my $i = 0; $i < scalar(@files); $i++) { + $doc_refs[$i] = 0; + $doc[$i] = qx(./scripts/kernel-doc --sphinx-version 3.2.1 $files[$i] 2>/dev/null); + } + + my @missing_exports; + my $found = -1; + foreach my $e (@exports) { + # Check if the symbol is a function + if (!($content =~ (m/\n\s*(?:\w+\s+){0,}\*?\s*\b\Q$e\E\b\s*\(/))) { + next; + } + for (my $i = 0; $i < scalar(@files); $i++) { + if ($doc[$i] =~ m/\b\Q$e\E\b/) { + $found = $i; + $doc_refs[$i]++; + last; + } + } + + push @missing_exports, $e if ($found < 0); + } + + if (@missing_exports) { + print "warning: $file: missing documentation for @missing_exports\n"; + } + + for (my $i = 0; $i < scalar(@files); $i++) { + next if (!$doc_refs[$i]); + my $includes = qx(git grep -l "kernel-doc::\\s*$files[$i]" Documentation/); + + printf "warning: %s: file not included at Documentation/\n", $files[$i] if ($includes eq ""); + } + return 1; +} + +sub parse_dir { + check_file $File::Find::name; +} + +# +# main +# + +my $file; + +if (@ARGV) { + while (@ARGV) { + my $file = shift; + + if (-d $file) { + find({wanted => \&parse_dir, no_chdir => 1}, $file); + } else { + check_file $file; + } + } + exit; +} else { + my @files = qx(git grep -l EXPORT_SYMBOL); + foreach $file (@files) { + $file =~ s/\s+$//; + check_file $file; + } +}
Signature · 1 line
2.26.2
Re: [PATCH RFC] script: add a script for checking doc problems with external functions
Hi Matthew/Jon,
Em Tue, 6 Oct 2020 13:53:34 +0200
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 10 lines
While not all EXPORT_SYMBOL*() symbols should be documented, it seems useful to have a tool which would help to check what symbols aren't documented.
This is a first step on this direction. The tool has some limitations. Yet, it could be useful for maintainers to check about missing documents on their subsystems.
Suggested-by Matthew Wilcox <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>
As suggested, I improved the script for it to provide some hints about what documentation is missing:
$ ./scripts/check_docs_external_symbols drivers/media/v4l2-core/ warning: drivers/media/v4l2-core/videobuf-dma-contig.c: missing documentation for videobuf_queue_dma_contig_init videobuf_to_dma_contig videobuf_dma_contig_free warning: drivers/media/v4l2-core/v4l2-clk.c: missing documentation for v4l2_clk_get v4l2_clk_put v4l2_clk_enable v4l2_clk_disable v4l2_clk_get_rate v4l2_clk_set_rate v4l2_clk_register v4l2_clk_unregister __v4l2_clk_register_fixed v4l2_clk_unregister_fixed warning: include/media/v4l2-h264.h: file not included at Documentation/ warning: drivers/media/v4l2-core/v4l2-h264.c: file not included at Documentation/ warning: drivers/media/v4l2-core/videobuf-core.c: missing documentation for videobuf_alloc_vb videobuf_waiton videobuf_iolock videobuf_queue_to_vaddr videobuf_queue_core_init videobuf_queue_is_busy videobuf_queue_cancel videobuf_next_field videobuf_mmap_free __videobuf_mmap_setup videobuf_mmap_setup videobuf_reqbufs videobuf_querybuf videobuf_qbuf videobuf_dqbuf videobuf_streamon videobuf_streamoff videobuf_read_one videobuf_read_start videobuf_read_stop videobuf_stop videobuf_read_stream videobuf_poll_stream videobuf_mmap_mapper warning: drivers/media/v4l2-core/v4l2-mem2mem.c: file not included at Documentation/ warning: drivers/media/v4l2-core/v4l2-dev.c: missing documentation for video_device_alloc video_device_release video_device_release_empty video_devdata v4l2_prio_init v4l2_prio_change v4l2_prio_open v4l2_prio_close v4l2_prio_max v4l2_prio_check __video_register_device warning: drivers/media/v4l2-core/v4l2-dev.c: file not included at Documentation/
It also report things that shouldn't be documented, like those:
$ ./scripts/check_docs_external_symbols drivers/media/pci/saa7134 warning: drivers/media/pci/saa7134/saa7134-video.c: missing documentation for saa7134_vb2_buffer_queue saa7134_enum_input saa7134_g_input saa7134_s_input saa7134_querycap saa7134_s_std saa7134_g_std saa7134_querystd saa7134_g_tuner saa7134_s_tuner saa7134_g_frequency saa7134_s_frequency warning: drivers/media/pci/saa7134/saa7134-core.c: missing documentation for saa7134_stop_streaming saa7134_ts_register saa7134_ts_unregister saa7134_set_gpio saa7134_dmasound_init saa7134_dmasound_exit saa7134_pgtable_free saa7134_pgtable_build saa7134_pgtable_alloc saa7134_set_dmabits warning: drivers/media/pci/saa7134/saa7134-ts.c: missing documentation for saa7134_ts_buffer_init saa7134_ts_buffer_prepare saa7134_ts_queue_setup saa7134_ts_start_streaming saa7134_ts_stop_streaming
On this specific case, the saa7134 driver was split into multiple drivers, depending on the PCI sub-interfaces found on some complex media devices. IMO, it doesn't make any sense to document such symbols, as they aren't meant to be used outside saa7134 sub-drivers.
-
As noticed on its comments, this script is not perfect. It tries to avoid reporting false-positives by not processing files that it can't find all includes and by skipping non-functions.
Yet, it can take a long time for it to parse the entire Kernel tree. So, at least on its current state, I don't think it would be a good idea to add it to the default build.
Feel free to either take it as-is, to improve it, or to ignore ;-)
Thanks,
Mauro
Re: [PATCH RFC] script: add a script for checking doc problems with external functions
In reply to Mauro Carvalho ChehabQuoted 7 lines · Mauro Carvalho Chehab
While not all EXPORT_SYMBOL*() symbols should be documented, it seems useful to have a tool which would help to check what symbols aren't documented.
This is a first step on this direction. The tool has some limitations. Yet, it could be useful for maintainers to check about missing documents on their subsystems.
Seems like this should be part of checkpatch.pl somehow.
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
Re: [PATCH RFC] script: add a script for checking doc problems with external functions
Quoted 10 lines · Jani Nikula
Quoted 7 lines · Mauro Carvalho Chehab
While not all EXPORT_SYMBOL*() symbols should be documented, it seems useful to have a tool which would help to check what symbols aren't documented.
This is a first step on this direction. The tool has some limitations. Yet, it could be useful for maintainers to check about missing documents on their subsystems.
Seems like this should be part of checkpatch.pl somehow.
I don't see how.
Re: [PATCH RFC] script: add a script for checking doc problems with external functions
Em Wed, 07 Oct 2020 01:32:31 -0700
Joe Perches <[email protected]> escreveu:
Quoted 6 lines · Jani Nikula
Quoted 5 lines · Mauro Carvalho Chehab
Quoted 4 lines
While not all EXPORT_SYMBOL*() symbols should be documented, it seems useful to have a tool which would help to check what symbols aren't documented.
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
This is a first step on this direction. The tool has some limitations. Yet, it could be useful for maintainers to check about missing documents on their subsystems.
Seems like this should be part of checkpatch.pl somehow.
I don't see how.
Just sent a third version of the script. It should now be able to check if the RST files have the exported symbols as well:
<snip>
$ scripts/check_docs_external_symbols lib/debugobjects.c lib/debugobjects.c: export symbol debug_object_active_state not documented at: Documentation/core-api/debug-objects.rst </snip>
It also checks if an exported symbol has duplicated entries at kernel-doc as well.
The check logic for it is somewhat complex. so, I won't doubt that there are some other hidden bugs.
Also, as right now, the script is slow, if one wants to run it for the entire Kernel.
Thanks,
Mauro