Fix several bad kernel-doc markups
Subsystems (23)
PATCH v6 15/16 drm: drm_crc: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype for drm_crtc_alloc_with_planes(). Prototype was for drmm_crtc_alloc_with_planes() instead
--- include/drm/drm_crtc.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/drm/drm_crtc.h +1 -1
@@ -1232,7 +1232,7 @@ void *__drmm_crtc_alloc_with_planes(struct drm_device *dev, const char *name, ...);/** -* drm_crtc_alloc_with_planes - Allocate and initialize a new CRTC object with +* drmm_crtc_alloc_with_planes - Allocate and initialize a new CRTC object with * specified primary and cursor planes. * @dev: DRM device * @type: the type of the struct which contains struct &drm_crtc
Signature · 6 lines
2.29.2 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
v6 cover Fix several bad kernel-doc markups
Hi Jon,
This series have three parts:
1) 10 remaining fixup patches from the series I sent back on Dec, 1st:
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
selftests: kselftest_harness.h: partially fix kernel-doc markups
2) The patch adding the new check to ensure that the kernel-doc markup will be used for the right declaration;
3) 5 additional patches, produced against next-20210114 with new problems detected after the original series:
net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup platform/surface: aggregator: fix a kernel-doc markup
It probably makes sense to merge at least the first 11 patches via the doc tree, as they should apply cleanly there, and having the last 5 patches merged via each maintainer's tree.
-
Kernel-doc has always be limited to a probably bad documented rule:
The kernel-doc markups should appear *imediatelly before* the function or data structure that it documents.
On other words, if a C file would contain something like this:
/** * foo - function foo * @args: foo args */ static inline void bar(int args); /** * bar - function bar * @args: foo args */ static inline void foo(void *args);
The output (in ReST format) will be:
.. c:function:: void bar (int args) function foo **Parameters** ``int args`` foo args .. c:function:: void foo (void *args) function bar **Parameters** ``void *args`` foo args
Which is clearly a wrong result. Before this changeset, not even a warning is produced on such cases.
As placing such markups just before the documented data is a common practice, on most cases this is fine.
However, as patches touch things, identifiers may be renamed, and people may forget to update the kernel-doc markups to follow such changes.
This has been happening for quite a while, as there are lots of files with kernel-doc problems.
This series address those issues and add a file at the end that will enforce that the identifier will match the kernel-doc markup, avoiding this problem from keep happening as time goes by.
This series is based on current upstream tree.
@maintainers: feel free to pick the patches and apply them directly on your trees, as all patches on this series are independent from the other ones.
--
v6:
- rebased on the top of next-20210114 and added a few extra fixes
v5:
- The completion.h patch was replaced by another one which drops
an obsolete macro;
- Some typos got fixed and review tags got added;
- Dropped patches that were already merged at linux-next.
v4:
- Patches got rebased and got some acks.
Mauro Carvalho Chehab (16):
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
selftests: kselftest_harness.h: partially fix kernel-doc markups
scripts: kernel-doc: validate kernel-doc markup with the actual names
net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup
platform/surface: aggregator: fix a kernel-doc markup
drivers/parport/share.c | 2 +- .../surface/aggregator/ssh_request_layer.c | 2 +- drivers/rapidio/rio.c | 2 +- drivers/reset/core.c | 4 +- fs/dcache.c | 73 ++++++++++--------- fs/inode.c | 4 +- fs/pstore/zone.c | 2 +- fs/seq_file.c | 5 +- fs/super.c | 12 +-- include/drm/drm_crtc.h | 2 +- include/linux/connector.h | 2 +- .../firmware/intel/stratix10-svc-client.h | 10 +-- include/linux/memblock.h | 4 +- include/linux/parport.h | 31 ++++++++ include/linux/w1.h | 2 +- include/net/cfg80211.h | 2 +- lib/crc7.c | 2 +- net/tipc/link.c | 2 +- net/tipc/node.c | 2 +- scripts/kernel-doc | 62 ++++++++++++---- tools/testing/selftests/kselftest_harness.h | 26 ++++--- 21 files changed, 160 insertions(+), 93 deletions(-)
Signature · 1 line
2.29.2
PATCH v6 8/16 memblock: fix kernel-doc markups
Some identifiers have different names between their prototypes and the kernel-doc markup.
--- include/linux/memblock.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/memblock.h +2 -2
@@ -272,7 +272,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,unsigned long *out_spfn, unsigned long *out_epfn);/** -* for_each_free_mem_range_in_zone - iterate through zone specific free +* for_each_free_mem_pfn_range_in_zone - iterate through zone specific free * memblock areas * @i: u64 used as loop variable * @zone: zone in which all of the memory blocks reside
@@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone, __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))/** -* for_each_free_mem_range_in_zone_from - iterate through zone specific +* for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific * free memblock areas from a given point * @i: u64 used as loop variable * @zone: zone in which all of the memory blocks reside
Signature · 1 line
2.29.2
PATCH v6 2/16 rapidio: fix kernel-doc a markup
In reply to Mauro Carvalho ChehabProbaly this was due to a cut and paste issue.
--- drivers/rapidio/rio.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/rapidio/rio.c +1 -1
@@ -749,7 +749,7 @@ int rio_map_outb_region(struct rio_mport *mport, u16 destid, u64 rbase,EXPORT_SYMBOL_GPL (rio_map_outb_region);/** -* rio_unmap_inb_region -- Unmap the inbound memory region +* rio_unmap_outb_region -- Unmap the inbound memory region * @mport: Master port * @destid: destination id mapping points to * @rstart: RIO base address window translates to
Signature · 1 line
2.29.2
PATCH v6 4/16 pstore/zone: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabThe documented struct is psz_head and not psz_buffer.
--- fs/pstore/zone.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
fs/pstore/zone.c +1 -1
@@ -23,7 +23,7 @@#include "internal.h" /** -* struct psz_head - header of zone to flush to storage +* struct psz_buffer - header of zone to flush to storage * * @sig: signature to indicate header (PSZ_SIG xor PSZONE-type value) * @datalen: length of data in @data
Signature · 1 line
2.29.2
PATCH v6 5/16 firmware: stratix10-svc: fix kernel-doc markups
In reply to Mauro Carvalho ChehabThere are some common comments marked, instead, with kernel-doc notation, which won't work.
While here, rename an identifier, in order to match the function prototype below kernel-doc markup.
--- include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
include/linux/firmware/intel/stratix10-svc-client.h +5 -5
@@ -6,7 +6,7 @@#ifndef __STRATIX10_SVC_CLIENT_H#define __STRATIX10_SVC_CLIENT_H -/** +/* * Service layer driver supports client names * * fpga: for FPGA configuration
@@ -15,7 +15,7 @@#define SVC_CLIENT_FPGA "fpga"#define SVC_CLIENT_RSU "rsu" -/** +/* * Status of the sent command, in bit number * * SVC_STATUS_OK:
@@ -50,7 +50,7 @@#define SVC_STATUS_ERROR 5#define SVC_STATUS_NO_SUPPORT 6 -/** +/* * Flag bit for COMMAND_RECONFIG * * COMMAND_RECONFIG_FLAG_PARTIAL:
@@ -58,7 +58,7 @@*/ #define COMMAND_RECONFIG_FLAG_PARTIAL 1 -/** +/* * Timeout settings for service clients: * timeout value used in Stratix10 FPGA manager driver. * timeout value used in RSU driver
@@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);int stratix10_svc_send (struct stratix10_svc_chan *chan,void *msg);/** -* intel_svc_done() - complete service request +* stratix10_svc_done() - complete service request * @chan: service channel assigned to the client * * This function is used by service client to inform service layer that
Signature · 1 line
2.29.2
PATCH v6 3/16 fs: fix kernel-doc markups
In reply to Mauro Carvalho ChehabTwo markups are at the wrong place. Kernel-doc only support having the comment just before the identifier.
Also, some identifiers have different names between their prototypes and the kernel-doc markup.
--- fs/dcache.c | 73 ++++++++++++++++++++++++++------------------------- fs/inode.c | 4 +-- fs/seq_file.c | 5 ++-- fs/super.c | 12 ++++----- 4 files changed, 48 insertions(+), 46 deletions(-)
fs/dcache.c +37 -36
@@ -456,23 +456,6 @@ static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,list_lru_isolate_move (lru, &dentry->d_lru, list); } -/** -* d_drop - drop a dentry -* @dentry: dentry to drop -* -* d_drop() unhashes the entry from the parent dentry hashes, so that it won't -* be found through a VFS lookup any more. Note that this is different from -* deleting the dentry - d_delete will try to mark the dentry negative if -* possible, giving a successful _negative_ lookup, while d_drop will -* just make the cache lookup fail. -* -* d_drop() is used mainly for stuff that wants to invalidate a dentry for some -* reason (NFS timeouts or autofs deletes). -* -* __d_drop requires dentry->d_lock -* ___d_drop doesn't mark dentry as "unhashed" -* (dentry->d_hash.pprev will be LIST_POISON2, not NULL). -*/ static void ___d_drop (struct dentry *dentry) {struct hlist_bl_head *b;
@@ -501,6 +484,24 @@ void __d_drop(struct dentry *dentry) }EXPORT_SYMBOL (__d_drop); +/** +* d_drop - drop a dentry +* @dentry: dentry to drop +* +* d_drop() unhashes the entry from the parent dentry hashes, so that it won't +* be found through a VFS lookup any more. Note that this is different from +* deleting the dentry - d_delete will try to mark the dentry negative if +* possible, giving a successful _negative_ lookup, while d_drop will +* just make the cache lookup fail. +* +* d_drop() is used mainly for stuff that wants to invalidate a dentry for some +* reason (NFS timeouts or autofs deletes). +* +* __d_drop requires dentry->d_lock +* +* ___d_drop doesn't mark dentry as "unhashed" +* (dentry->d_hash.pprev will be LIST_POISON2, not NULL). +*/ void d_drop (struct dentry *dentry) {spin_lock (&dentry->d_lock);
@@ -996,6 +997,25 @@ struct dentry *d_find_any_alias(struct inode *inode) }EXPORT_SYMBOL (d_find_any_alias); +static struct dentry *__d_find_alias (struct inode *inode) +{ +struct dentry *alias; + +if (S_ISDIR (inode->i_mode)) +return __d_find_any_alias (inode); + +hlist_for_each_entry (alias, &inode->i_dentry, d_u.d_alias) { +spin_lock (&alias->d_lock); +if (!d_unhashed (alias)) { +__dget_dlock (alias); +spin_unlock (&alias->d_lock); +return alias; + } +spin_unlock (&alias->d_lock); + } +return NULL ; +} +/** * d_find_alias - grab a hashed alias of inode * @inode: inode in question
@@ -1010,25 +1030,6 @@ EXPORT_SYMBOL(d_find_any_alias);* If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer * any other hashed alias over that one. */ -static struct dentry *__d_find_alias (struct inode *inode) -{ -struct dentry *alias; - -if (S_ISDIR (inode->i_mode)) -return __d_find_any_alias (inode); - -hlist_for_each_entry (alias, &inode->i_dentry, d_u.d_alias) { -spin_lock (&alias->d_lock); -if (!d_unhashed (alias)) { -__dget_dlock (alias); -spin_unlock (&alias->d_lock); -return alias; - } -spin_unlock (&alias->d_lock); - } -return NULL ; -} -struct dentry *d_find_alias (struct inode *inode) {struct dentry *de =NULL ;
fs/inode.c +2 -2
@@ -1494,7 +1494,7 @@ struct inode *find_inode_rcu(struct super_block *sb, unsigned long hashval,EXPORT_SYMBOL (find_inode_rcu);/** -* find_inode_by_rcu - Find an inode in the inode cache +* find_inode_by_ino_rcu - Find an inode in the inode cache * @sb: Super block of file system to search * @ino: The inode number to match *
@@ -1780,7 +1780,7 @@ static int update_time(struct inode *inode, struct timespec64 *time, int flags) }/** -* touch_atime - update the access time +* atime_needs_update - update the access time * @path: the &struct path to update * @inode: inode to update *
fs/seq_file.c +3 -2
@@ -669,7 +669,8 @@ void seq_puts(struct seq_file *m, const char *s)EXPORT_SYMBOL (seq_puts);/** -* A helper routine for putting decimal numbers without rich format of printf(). +* seq_put_decimal_ull_width - A helper routine for putting decimal numbers +* without rich format of printf(). * only 'unsigned long long' is supported. * @m: seq_file identifying the buffer to which data should be written * @delimiter: a string which is printed before the number
@@ -1044,7 +1045,7 @@ struct hlist_node *seq_hlist_next_rcu(void *v,EXPORT_SYMBOL (seq_hlist_next_rcu);/** -* seq_hlist_start_precpu - start an iteration of a percpu hlist array +* seq_hlist_start_percpu - start an iteration of a percpu hlist array * @head: pointer to percpu array of struct hlist_heads * @cpu: pointer to cpu "cursor" * @pos: start position of sequence
fs/super.c +6 -6
@@ -1718,12 +1718,6 @@ int freeze_super(struct super_block *sb) }EXPORT_SYMBOL (freeze_super); -/** -* thaw_super -- unlock filesystem -* @sb: the super to thaw -* -* Unlocks the filesystem and marks it writeable again after freeze_super(). -*/ static int thaw_super_locked (struct super_block *sb) {int error;
@@ -1759,6 +1753,12 @@ static int thaw_super_locked(struct super_block *sb)return 0 ; } +/** +* thaw_super -- unlock filesystem +* @sb: the super to thaw +* +* Unlocks the filesystem and marks it writeable again after freeze_super(). +*/ int thaw_super (struct super_block *sb) {down_write (&sb->s_umount);
Signature · 1 line
2.29.2
PATCH v6 6/16 connector: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup.
--- include/linux/connector.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/connector.h +1 -1
@@ -99,7 +99,7 @@ void cn_del_callback(const struct cb_id *id);int cn_netlink_send_mult (struct cn_msg *msg,u16 len,u32 portid,u32 group,gfp_t gfp_mask);/** -* cn_netlink_send_mult - Sends message to the specified groups. +* cn_netlink_send - Sends message to the specified groups. * * @msg: message header(with attached data). * @portid: destination port.
Signature · 1 line
2.29.2
PATCH v6 9/16 w1: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup.
--- include/linux/w1.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/w1.h +1 -1
@@ -280,7 +280,7 @@ int w1_register_family(struct w1_family *family);void w1_unregister_family (struct w1_family *family);/** -* module_w1_driver() - Helper macro for registering a 1-Wire families +* module_w1_family() - Helper macro for registering a 1-Wire families * @__w1_family: w1_family struct * * Helper macro for 1-Wire families which do not do anything special in module
Signature · 1 line
2.29.2
PATCH v6 13/16 net: cfg80211: fix a kerneldoc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype
and its kernel-doc markup:
../include/net/cfg80211.h:1766: warning: expecting prototype for struct cfg80211_sar_chan_ranges. Prototype was for struct cfg80211_sar_freq_ranges instead
--- include/net/cfg80211.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/net/cfg80211.h +1 -1
@@ -1756,7 +1756,7 @@ struct cfg80211_sar_specs {/** -* struct cfg80211_sar_chan_ranges - sar frequency ranges +* struct cfg80211_sar_freq_ranges - sar frequency ranges * @start_freq: start range edge frequency * @end_freq: end range edge frequency */
Signature · 1 line
2.29.2
Re: [PATCH v6 15/16] drm: drm_crc: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabQuoted 6 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype fordrm_crtc_alloc_with_planes(). Prototype was fordrmm_crtc_alloc_with_planes()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH v6 1/16 parport: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabThe kernel-doc markup inside share.c is actually for __parport_register_driver. The actual goal seems to be to document parport_register_driver().
So, fix the existing markup and add a new one.
--- drivers/parport/share.c | 2 +- include/linux/parport.h | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-)
drivers/parport/share.c +1 -1
@@ -243,7 +243,7 @@ static int port_detect(struct device *dev, void *dev_drv) }/** -* parport_register_driver - register a parallel port device driver +* __parport_register_driver - register a parallel port device driver * @drv: structure describing the driver * @owner: owner module of drv * @mod_name: module name string
include/linux/parport.h +31 -0
@@ -297,6 +297,37 @@ int __must_check __parport_register_driver(struct parport_driver *,* parport_register_driver must be a macro so that KBUILD_MODNAME can * be expanded */ + +/** +* parport_register_driver - register a parallel port device driver +* @driver: structure describing the driver +* +* This can be called by a parallel port device driver in order +* to receive notifications about ports being found in the +* system, as well as ports no longer available. +* +* If devmodel is true then the new device model is used +* for registration. +* +* The @driver structure is allocated by the caller and must not be +* deallocated until after calling parport_unregister_driver(). +* +* If using the non device model: +* The driver's attach() function may block. The port that +* attach() is given will be valid for the duration of the +* callback, but if the driver wants to take a copy of the +* pointer it must call parport_get_port() to do so. Calling +* parport_register_device() on that port will do this for you. +* +* The driver's detach() function may block. The port that +* detach() is given will be valid for the duration of the +* callback, but if the driver wants to take a copy of the +* pointer it must call parport_get_port() to do so. +* +* +* Returns 0 on success. The non device model will always succeeds. +* but the new device model can fail and will return the error code. +**/ #define parport_register_driver (driver) \ __parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
Signature · 1 line
2.29.2
PATCH v6 10/16 selftests: kselftest_harness.h: partially fix kernel-doc markups
In reply to Mauro Carvalho ChehabThe kernel-doc markups on this file are weird: they don't follow what's specified at:
Documentation/doc-guide/kernel-doc.rst
In particular, markups should use this format:
identifier - description
and not this:
identifier(args)
The way the definitions are inside this file cause the parser to completely miss the identifier name of each function.
This prevents improving the script to do some needed validation tests.
Address this part. Yet, furter changes are needed in order for it to fully follow the specs.
--- tools/testing/selftests/kselftest_harness.h | 26 ++++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-)
tools/testing/selftests/kselftest_harness.h +15 -11
@@ -79,7 +79,7 @@#endif /** -* TH_LOG(fmt, ...) +* TH_LOG() * * @fmt: format string * @...: optional arguments
@@ -113,12 +113,16 @@ __FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)/** -* SKIP(statement, fmt, ...) +* SKIP() * * @statement: statement to run after reporting SKIP * @fmt: format string * @...: optional arguments * +* .. code-block:: c +* +* SKIP(statement, fmt, ...); +* * This forces a "pass" after reporting why something is being skipped * and runs "statement", which is usually "return" or "goto skip". */
@@ -136,7 +140,7 @@ }while (0 )/** -* TEST(test_name) - Defines the test function and creates the registration +* TEST() - Defines the test function and creates the registration * stub * * @test_name: test name
@@ -155,7 +159,7 @@#define TEST (test_name) __TEST_IMPL(test_name, -1)/** -* TEST_SIGNAL(test_name, signal) +* TEST_SIGNAL() * * @test_name: test name * @signal: signal number
@@ -195,7 +199,7 @@ struct __test_metadata __attribute__((unused)) *_metadata)/** -* FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less +* FIXTURE_DATA() - Wraps the struct name so we have one less * argument to pass around * * @datatype_name: datatype name
@@ -212,7 +216,7 @@#define FIXTURE_DATA (datatype_name) struct _test_data_##datatype_name/** -* FIXTURE(fixture_name) - Called once per fixture to setup the data and +* FIXTURE() - Called once per fixture to setup the data and * register * * @fixture_name: fixture name
@@ -239,7 +243,7 @@FIXTURE_DATA (fixture_name)/** -* FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture. +* FIXTURE_SETUP() - Prepares the setup function for the fixture. * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly. * * @fixture_name: fixture name
@@ -265,7 +269,7 @@ __attribute__((unused)) *variant)/** -* FIXTURE_TEARDOWN(fixture_name) +* FIXTURE_TEARDOWN() * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly. * * @fixture_name: fixture name
@@ -286,7 +290,7 @@ FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)/** -* FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture +* FIXTURE_VARIANT() - Optionally called once per fixture * to declare fixture variant * * @fixture_name: fixture name
@@ -305,7 +309,7 @@#define FIXTURE_VARIANT (fixture_name) struct _fixture_variant_##fixture_name/** -* FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture +* FIXTURE_VARIANT_ADD() - Called once per fixture * variant to setup and register the data * * @fixture_name: fixture name
@@ -339,7 +343,7 @@ _##fixture_name##_##variant_name##_variant =/** -* TEST_F(fixture_name, test_name) - Emits test registration and helpers for +* TEST_F() - Emits test registration and helpers for * fixture-based test cases * * @fixture_name: fixture name
Signature · 1 line
2.29.2
PATCH v6 11/16 scripts: kernel-doc: validate kernel-doc markup with the actual names
In reply to Mauro Carvalho ChehabKernel-doc currently expects that the kernel-doc markup to come just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/** * refcount_add - add a value to a refcount * @i: the value to add to the refcount * @r: the refcount */ static inline void __refcount_add(int i, refcount_t *r, int *oldp); static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add' .. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp) add a value to a refcount **Parameters** ``int i`` the value to add to the refcount ``refcount_t *r`` the refcount ``int *oldp`` *undescribed*
Basically, it will document "__refcount_add" with the kernel-doc markup for refcount_add.
If both functions have the same arguments, this won't even produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual name of the C function or data structure that will be documented.
--- scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 16 deletions(-)
scripts/kernel-doc +46 -16
@@ -382,6 +382,9 @@ my $inline_doc_state; # 'function', 'struct', 'union', 'enum', 'typedef' my $decl_type; +# Name of the kernel-doc identifier for non-DOC markups +my $identifier; + my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. my $doc_end = '\*/'; my $doc_com = '\s*\*\s*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) { $declaration_name = $2; my $members = $3; + if ($identifier ne $declaration_name) { + print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n"; + return; + } + # ignore members marked private: $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; $members =~ s/\/\*\s*private:.*//gosi;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) { } if ($members) { + if ($identifier ne $declaration_name) { + print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + return; + } + my %_members; $members =~ s/\s+$//;
@@ -1451,6 +1464,11 @@ sub dump_typedef($$) { my $args = $3; $return_type =~ s/^\s+//; + if ($identifier ne $declaration_name) { + print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"; + return; + } + create_parameterlist($args, ',', $file, $declaration_name); output_declaration($declaration_name,
@@ -1477,6 +1495,11 @@ sub dump_typedef($$) { if ($x =~ /typedef.*\s+(\w+)\s*;/) { $declaration_name = $1; + if ($identifier ne $declaration_name) { + print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"; + return; + } + output_declaration($declaration_name, 'typedef', {'typedef' => $declaration_name,
@@ -1796,6 +1819,11 @@ sub dump_function($$) { return; } + if ($identifier ne $declaration_name) { + print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n"; + return; + } + my $prms = join " ", @parameterlist; check_sections($file, $declaration_name, "function", $sectcheck, $prms);
@@ -1878,6 +1906,7 @@ sub tracepoint_munge($) { "$prototype\n"; } else { $prototype = "static inline void trace_$tracepointname($tracepointargs)"; + $identifier = "trace_$identifier"; } }
@@ -2041,7 +2070,6 @@ sub process_normal() { # sub process_name($$) { my $file = shift; - my $identifier; my $descr; if (/$doc_block/o) {
@@ -2054,12 +2082,19 @@ sub process_name($$) { } else { $section = $1; } - } - elsif (/$doc_decl/o) { + } elsif (/$doc_decl/o) { $identifier = $1; - if (/\s*([\w\s]+?)(\(\))?\s*-/) { + if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { $identifier = $1; } + if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { + $decl_type = $1; + $identifier = $2; + } else { + $decl_type = 'function'; + $identifier =~ s/^define\s+//; + } + $identifier =~ s/\s+$//; $state = STATE_BODY; # if there's no @param blocks need to set up default section
@@ -2067,7 +2102,7 @@ sub process_name($$) { $contents = ""; $section = $section_default; $new_start_line = $. + 1; - if (/-(.*)/) { + if (/[-:](.*)/) { # strip leading/trailing/multiple spaces $descr= $1; $descr =~ s/^\s*//;
@@ -2085,20 +2120,15 @@ sub process_name($$) { ++$warnings; } - if ($identifier =~ m/^struct\b/) { - $decl_type = 'struct'; - } elsif ($identifier =~ m/^union\b/) { - $decl_type = 'union'; - } elsif ($identifier =~ m/^enum\b/) { - $decl_type = 'enum'; - } elsif ($identifier =~ m/^typedef\b/) { - $decl_type = 'typedef'; - } else { - $decl_type = 'function'; + if ($identifier eq "") { + print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; + print STDERR $_; + ++$warnings; + $state = STATE_NORMAL; } if ($verbose) { - print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; + print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n"; } } else { print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
Signature · 1 line
2.29.2
PATCH v6 12/16 net: tip: fix a couple kernel-doc markups
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup:
../net/tipc/link.c:2551: warning: expecting prototype for link_reset_stats(). Prototype was for tipc_link_reset_stats() instead ../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for message sending(). Prototype was for tipc_node_xmit() instead
--- net/tipc/link.c | 2 +- net/tipc/node.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)
net/tipc/link.c +1 -1
@@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win) }/** -* link_reset_stats - reset link statistics +* tipc_link_reset_stats - reset link statistics * @l: pointer to link */ void tipc_link_reset_stats (struct tipc_link *l)
net/tipc/node.c +1 -1
@@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list) }/** -* tipc_node_xmit() is the general link level function for message sending +* tipc_node_xmit() - general link level function for message sending * @net: the applicable net namespace * @list: chain of buffers containing message * @dnode: address of destination node
Signature · 1 line
2.29.2
PATCH v6 14/16 reset: core: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup:
../drivers/reset/core.c:888: warning: expecting prototype for device_reset(). Prototype was for __device_reset() instead
--- drivers/reset/core.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/reset/core.c +2 -2
@@ -875,8 +875,8 @@ struct reset_control *__devm_reset_control_get(struct device *dev,EXPORT_SYMBOL_GPL (__devm_reset_control_get);/** -* device_reset - find reset controller associated with the device -* and perform reset +* __device_reset - find reset controller associated with the device +* and perform reset * @dev: device to be reset by the controller * @optional: whether it is optional to reset the device *
Signature · 1 line
2.29.2
PATCH v6 16/16 platform/surface: aggregator: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype for ssh_rtl_tx_start(). Prototype was for ssh_rtl_start() instead
--- drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/platform/surface/aggregator/ssh_request_layer.c +1 -1
@@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl) }/** -* ssh_rtl_tx_start() - Start request transmitter and receiver. +* ssh_rtl_start() - Start request transmitter and receiver. * @rtl: The request transport layer. * * Return: Returns zero on success, a negative error code on failure.
Signature · 1 line
2.29.2
PATCH v6 7/16 lib/crc7: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabA function has a different name between their prototype and its kernel-doc markup.
--- lib/crc7.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
lib/crc7.c +1 -1
@@ -51,7 +51,7 @@ const u8 crc7_be_syndrome_table[256] = {EXPORT_SYMBOL (crc7_be_syndrome_table);/** -* crc7 - update the CRC7 for the data buffer +* crc7_be - update the CRC7 for the data buffer * @crc: previous CRC7 value * @buffer: data pointer * @len: number of bytes in the buffer
Signature · 1 line
2.29.2
Re: [PATCH v6 14/16] reset: core: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabHi Mauro,
Quoted 15 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../drivers/reset/core.c:888: warning: expecting prototype fordevice_reset(). Prototype was for__device_reset()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>--- drivers/reset/core.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)drivers/reset/core.c +0
-0
drivers/reset/core.c struct reset_control *__devm_reset_control_get(struct device *dev, · line 882
Quoted 10 lines
drivers/reset/core.c +2
-2@@ -875,8 +875,8 @@ struct reset_control *__devm_reset_control_get(struct device *dev,EXPORT_SYMBOL_GPL (__devm_reset_control_get);/** -* device_reset - find reset controller associated with the device -* and perform reset +* __device_reset - find reset controller associated with the device +* and perform reset * @dev: device to be reset by the controller * @optional: whether it is optional to reset the device *
Thank you, applied to reset/next.
regards
Philipp
kernel test robot
build botRe: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
In reply to Mauro Carvalho ChehabI love your patch! Perhaps something to improve:
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1] [If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010 base: aa515cdce7a151dcc14b7600d33f1414c6fa32c9 config: arm64-alldefconfig (attached as .config) compiler: aarch64-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross chmod +x ~/bin/make.cross
# https://github.com/0day-ci/linux/commit/1e9159b3640012fc5fab8508b1c5635ac13a55e9
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010 git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=arm64
If you fix the issue, kindly add following tag as appropriate
All warnings (new ones prefixed by >>):
kernel/seccomp.c:126: warning: Function parameter or member 'list' not described in 'seccomp_kaddfd' kernel/seccomp.c:390: warning: Function parameter or member 'ret' not described in 'ACTION_ONLY'
>> kernel/seccomp.c:390: warning: expecting prototype for seccomp_run_filters(). Prototype was for ACTION_ONLY() instead
kernel/seccomp.c:553: warning: Function parameter or member 'tsk' not described in 'seccomp_filter_release' kernel/seccomp.c:573: warning: Function parameter or member 'flags' not described in 'seccomp_sync_threads'
--
drivers/base/platform-msi.c:336: warning: Function parameter or member 'is_tree' not described in '__platform_msi_create_device_domain'
>> drivers/base/platform-msi.c:336: warning: expecting prototype for platform_msi_create_device_domain(). Prototype was for __platform_msi_create_device_domain() instead -- >> drivers/iommu/iommu.c:956: warning: expecting prototype for iommu_group_for_each_dev(). Prototype was for __iommu_group_for_each_dev() instead drivers/iommu/iommu.c:2976: warning: Function parameter or member 'drvdata' not described in 'iommu_sva_bind_device' -- >> kernel/irq/msi.c:534: warning: expecting prototype for __msi_domain_free_irqs(). Prototype was for msi_domain_free_irqs() instead -- >> kernel/irq/ipi.c:264: warning: expecting prototype for ipi_send_mask(). Prototype was for __ipi_send_mask() instead
vim +390 kernel/seccomp.c
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 380
e2cfabdfd0756482 Will Drewry 2012-04-12 381 /**
285fdfc5d9959a21 Mickaël Salaün 2016-09-20 382 * seccomp_run_filters - evaluates all seccomp filters against @sd
285fdfc5d9959a21 Mickaël Salaün 2016-09-20 383 * @sd: optional seccomp data to be passed to filters
deb4de8b31bc5bf2 Kees Cook 2017-08-02 384 * @match: stores struct seccomp_filter that resulted in the return value,
deb4de8b31bc5bf2 Kees Cook 2017-08-02 385 * unless filter returned SECCOMP_RET_ALLOW, in which case it will
deb4de8b31bc5bf2 Kees Cook 2017-08-02 386 * be unchanged.
e2cfabdfd0756482 Will Drewry 2012-04-12 387 *
e2cfabdfd0756482 Will Drewry 2012-04-12 388 * Returns valid seccomp BPF response codes.
e2cfabdfd0756482 Will Drewry 2012-04-12 389 */
0466bdb99e8744bc Kees Cook 2017-08-11 @390 #define ACTION_ONLY(ret) ((s32)((ret) & (SECCOMP_RET_ACTION_FULL)))
deb4de8b31bc5bf2 Kees Cook 2017-08-02 391 static u32 seccomp_run_filters(const struct seccomp_data *sd,
deb4de8b31bc5bf2 Kees Cook 2017-08-02 392 struct seccomp_filter **match)
e2cfabdfd0756482 Will Drewry 2012-04-12 393 {
acf3b2c71ed20c53 Will Drewry 2012-04-12 394 u32 ret = SECCOMP_RET_ALLOW;
8225d3853f34f6cf Pranith Kumar 2014-11-21 395 /* Make sure cross-thread synced filter points somewhere sane. */
8225d3853f34f6cf Pranith Kumar 2014-11-21 396 struct seccomp_filter *f =
506458efaf153c1e Will Deacon 2017-10-24 397 READ_ONCE(current->seccomp.filter);
acf3b2c71ed20c53 Will Drewry 2012-04-12 398
acf3b2c71ed20c53 Will Drewry 2012-04-12 399 /* Ensure unexpected behavior doesn't result in failing open. */
0d42d73a37ff9102 Igor Stoppa 2018-09-05 400 if (WARN_ON(f == NULL))
4d3b0b05aae9ee9c Kees Cook 2017-08-11 401 return SECCOMP_RET_KILL_PROCESS;
acf3b2c71ed20c53 Will Drewry 2012-04-12 402
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 403 if (seccomp_cache_check_allow(f, sd))
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 404 return SECCOMP_RET_ALLOW;
f9d480b6ffbeb336 YiFei Zhu 2020-10-11 405
e2cfabdfd0756482 Will Drewry 2012-04-12 406 /*
e2cfabdfd0756482 Will Drewry 2012-04-12 407 * All filters in the list are evaluated and the lowest BPF return
acf3b2c71ed20c53 Will Drewry 2012-04-12 408 * value always takes priority (ignoring the DATA).
e2cfabdfd0756482 Will Drewry 2012-04-12 409 */
3ba2530cc06eb4ae Kees Cook 2014-06-27 410 for (; f; f = f->prev) {
3d9f773cf2876c01 David Miller 2020-02-24 411 u32 cur_ret = bpf_prog_run_pin_on_cpu(f->prog, sd);
8f577cadf7181243 Alexei Starovoitov 2014-05-13 412
0466bdb99e8744bc Kees Cook 2017-08-11 413 if (ACTION_ONLY(cur_ret) < ACTION_ONLY(ret)) {
acf3b2c71ed20c53 Will Drewry 2012-04-12 414 ret = cur_ret;
deb4de8b31bc5bf2 Kees Cook 2017-08-02 415 *match = f;
deb4de8b31bc5bf2 Kees Cook 2017-08-02 416 }
e2cfabdfd0756482 Will Drewry 2012-04-12 417 }
e2cfabdfd0756482 Will Drewry 2012-04-12 418 return ret;
e2cfabdfd0756482 Will Drewry 2012-04-12 419 }
1f41b450416e689b Kees Cook 2014-06-25 420 #endif /* CONFIG_SECCOMP_FILTER */
1f41b450416e689b Kees Cook 2014-06-25 421 ---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/[email protected]
kernel test robot
build botRe: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
In reply to Mauro Carvalho ChehabI love your patch! Perhaps something to improve:
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on next-20210113]
[also build test WARNING on v5.11-rc3]
[cannot apply to lwn/docs-next kees/for-next/pstore mac80211-next/master mac80211/master pza/reset/next linus/master v5.11-rc3 v5.11-rc2 v5.11-rc1] [If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010 base: aa515cdce7a151dcc14b7600d33f1414c6fa32c9 config: mips-nlm_xlp_defconfig (attached as .config) compiler: mips64-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross chmod +x ~/bin/make.cross
# https://github.com/0day-ci/linux/commit/1e9159b3640012fc5fab8508b1c5635ac13a55e9
git remote add linux-review https://github.com/0day-ci/linux
git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20210114-161010 git checkout 1e9159b3640012fc5fab8508b1c5635ac13a55e9
# save the attached .config to linux build tree
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=mips
If you fix the issue, kindly add following tag as appropriate
All warnings (new ones prefixed by >>):
arch/mips/kernel/module.c:289: warning: Function parameter or member 'reloc_handler' not described in 'int'
>> arch/mips/kernel/module.c:289: warning: expecting prototype for reloc_handler(). Prototype was for int() instead
--
arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'p' not described in 'evaluate_branch_instruction' arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'regs' not described in 'evaluate_branch_instruction' arch/mips/kernel/kprobes.c:196: warning: Function parameter or member 'kcb' not described in 'evaluate_branch_instruction'
>> arch/mips/kernel/kprobes.c:196: warning: expecting prototype for evaluate_branch_instrucion(). Prototype was for evaluate_branch_instruction() instead
vim +289 arch/mips/kernel/module.c
5d3c792583b60406 Paul Burton 2016-02-04 272 430d0b88943afffd Paul Burton 2017-03-30 273 /** 430d0b88943afffd Paul Burton 2017-03-30 274 * reloc_handler() - Apply a particular relocation to a module 430d0b88943afffd Paul Burton 2017-03-30 275 * @me: the module to apply the reloc to 430d0b88943afffd Paul Burton 2017-03-30 276 * @location: the address at which the reloc is to be applied 430d0b88943afffd Paul Burton 2017-03-30 277 * @base: the existing value at location for REL-style; 0 for RELA-style 430d0b88943afffd Paul Burton 2017-03-30 278 * @v: the value of the reloc, with addend for RELA-style 430d0b88943afffd Paul Burton 2017-03-30 279 * 430d0b88943afffd Paul Burton 2017-03-30 280 * Each implemented reloc_handler function applies a particular type of 430d0b88943afffd Paul Burton 2017-03-30 281 * relocation to the module @me. Relocs that may be found in either REL or RELA 430d0b88943afffd Paul Burton 2017-03-30 282 * variants can be handled by making use of the @base & @v parameters which are 430d0b88943afffd Paul Burton 2017-03-30 283 * set to values which abstract the difference away from the particular reloc 430d0b88943afffd Paul Burton 2017-03-30 284 * implementations. 430d0b88943afffd Paul Burton 2017-03-30 285 * 430d0b88943afffd Paul Burton 2017-03-30 286 * Return: 0 upon success, else -ERRNO 430d0b88943afffd Paul Burton 2017-03-30 287 */ 430d0b88943afffd Paul Burton 2017-03-30 288 typedef int (*reloc_handler)(struct module *me, u32 *location,
430d0b88943afffd Paul Burton 2017-03-30 @289 u32 base, Elf_Addr v, bool rela);430d0b88943afffd Paul Burton 2017-03-30 290
---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all(a)lists.01.org
Re: [PATCH v6 15/16] drm: drm_crc: fix a kernel-doc markup
In reply to Simon SerQuoted 10 lines · Simon Ser
Quoted 6 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../include/drm/drm_crtc.h:1257: warning: expecting prototype fordrm_crtc_alloc_with_planes(). Prototype was fordrmm_crtc_alloc_with_planes()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>Acked-by Simon Ser <[email protected]>
Pushed to drm-misc-next, thanks for the fix!
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Re: [PATCH v6 16/16] platform/surface: aggregator: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabQuoted 16 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype forssh_rtl_tx_start(). Prototype was forssh_rtl_start()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>--- drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/platform/surface/aggregator/ssh_request_layer.c +0
-0
drivers/platform/surface/aggregator/ssh_request_layer.c void ssh_rtl_destroy(struct ssh_rtl *rtl) · line 1062
Quoted 8 lines
drivers/platform/surface/aggregator/ssh_request_layer.c +1
-1@@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl) }/** -* ssh_rtl_tx_start() - Start request transmitter and receiver. +* ssh_rtl_start() - Start request transmitter and receiver. * @rtl: The request transport layer. * * Return: Returns zero on success, a negative error code on failure.
Thanks! Looks good to me.
There seems to be another issue similar to this, specifically the non-existing ssh_rtl_tx_start() and ssh_rtl_tx_start() are referenced. Both should point to to ssh_rtl_start() instead. I'll start working on a patch to fix that right away.
Regards,
Max
Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
In reply to Mauro Carvalho ChehabQuoted 30 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../net/tipc/link.c:2551: warning: expecting prototype forlink_reset_stats(). Prototype was fortipc_link_reset_stats()instead../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for messagesending(). Prototype was fortipc_node_xmit()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>--- net/tipc/link.c | 2 +- net/tipc/node.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)net/tipc/link.c +1
-1@@ -2544,7 +2544,7 @@ void tipc_link_set_queue_limits(struct tipc_link *l, u32 min_win, u32 max_win) }/** -* link_reset_stats - reset link statistics +* tipc_link_reset_stats - reset link statistics * @l: pointer to link */ void tipc_link_reset_stats (struct tipc_link *l)net/tipc/node.c +0
-0
net/tipc/node.c static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list) · line 1671
Quoted 8 lines
net/tipc/node.c +1
-1@@ -1665,7 +1665,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list) }/** -* tipc_node_xmit() is the general link level function for message sending +* tipc_node_xmit() - general link level function for message sending * @net: the applicable net namespace * @list: chain of buffers containing message * @dnode: address of destination node
Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
Quoted 10 lines · On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
Quoted 7 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../net/tipc/link.c:2551: warning: expecting prototype forlink_reset_stats(). Prototype was fortipc_link_reset_stats()instead../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for messagesending(). Prototype was fortipc_node_xmit()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>Acked-by Jon Maloy <[email protected]>
Thanks! Applied this one to net, the cfg80211 one does not apply to net, so I'll leave it to Johannes.
Re: [PATCH v6 12/16] net: tip: fix a couple kernel-doc markups
Quoted 8 lines · Jakub Kicinski
Quoted 7 lines · On Thu, 14 Jan 2021 10:59:08 -0500 Jon Maloy wrote:
Quoted 6 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../net/tipc/link.c:2551: warning: expecting prototype forlink_reset_stats(). Prototype was fortipc_link_reset_stats()instead../net/tipc/node.c:1678: warning: expecting prototype for is the general link level function for messagesending(). Prototype was fortipc_node_xmit()instead
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
Signed-off-by Mauro Carvalho Chehab <[email protected]>Acked-by Jon Maloy <[email protected]>Thanks! Applied this one to net, the cfg80211 one does not apply to net, so I'll leave it to Johannes.
Right, that was diffed against -next, and I've got a fix pending that I didn't send yet.
I've applied this now, thanks.
johannes
Re: [PATCH v6 16/16] platform/surface: aggregator: fix a kernel-doc markup
In reply to Mauro Carvalho ChehabHi,
Quoted 6 lines · Mauro Carvalho Chehab
A function has a different name between their prototype and its kernel-doc markup:
../drivers/platform/surface/aggregator/ssh_request_layer.c:1065: warning: expecting prototype forssh_rtl_tx_start(). Prototype was forssh_rtl_start()insteadSigned-off-by Mauro Carvalho Chehab <[email protected]>
Thank you for your patch, I've applied this patch to my review-hans branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
Note it will show up in my review-hans branch once I've pushed my local branch there, which might take a while.
Once I've run some tests on this branch the patches there will be added to the platform-drivers-x86/for-next branch and eventually will be included in the pdx86 pull-request to Linus for the next merge-window.
Regards,
Hans
Quoted 18 lines
--- drivers/platform/surface/aggregator/ssh_request_layer.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/platform/surface/aggregator/ssh_request_layer.c +1
-1@@ -1056,7 +1056,7 @@ void ssh_rtl_destroy(struct ssh_rtl *rtl) }/** -* ssh_rtl_tx_start() - Start request transmitter and receiver. +* ssh_rtl_start() - Start request transmitter and receiver. * @rtl: The request transport layer. * * Return: Returns zero on success, a negative error code on failure.
Jonathan Corbet
maintainerRe: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
In reply to Mauro Carvalho ChehabQuoted 34 lines · On Thu, 14 Jan 2021 09:04:47 +0100 Mauro Carvalho Chehab…
Kernel-doc currently expects that the kernel-doc markup to come just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/** * refcount_add - add a value to a refcount * @i: the value to add to the refcount * @r: the refcount */ static inline void __refcount_add(int i, refcount_t *r, int *oldp); static inline void refcount_add(int i, refcount_t *r);Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add' .. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp) add a value to a refcount **Parameters** ``int i`` the value to add to the refcount ``refcount_t *r`` the refcount ``int *oldp`` *undescribed*Basically, it will document "
__refcount_add" with the kernel-doc markup forrefcount_add.
Quoted 7 lines
If both functions have the same arguments, this won't even produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual name of the C function or data structure that will be documented.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
I've applied this one; it seems useful to have even if it creates more warnings that Stephen will duly email me about tomorrow...:) I have parts 1-10 set aside and will apply any that don't get picked up directly by the maintainers involved.
Thanks,
jon
Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
Em Mon, 18 Jan 2021 13:35:45 -0700
Jonathan Corbet <[email protected]> escreveu:
Quoted 40 lines
Quoted 37 lines · On Thu, 14 Jan 2021 09:04:47 +0100 Mauro Carvalho Chehab…
Kernel-doc currently expects that the kernel-doc markup to come just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/** * refcount_add - add a value to a refcount * @i: the value to add to the refcount * @r: the refcount */ static inline void __refcount_add(int i, refcount_t *r, int *oldp); static inline void refcount_add(int i, refcount_t *r);Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add' .. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp) add a value to a refcount **Parameters** ``int i`` the value to add to the refcount ``refcount_t *r`` the refcount ``int *oldp`` *undescribed*Basically, it will document "
__refcount_add" with the kernel-doc markup forrefcount_add.If both functions have the same arguments, this won't even produce any warning!
Quoted 6 lines
Quoted 4 lines
Add a logic to check if the kernel-doc identifier matches the actual name of the C function or data structure that will be documented.
Signed-off-by Mauro Carvalho Chehab <[email protected]>I've applied this one;
Thanks!
Quoted 4 lines
it seems useful to have even if it creates more
warnings that Stephen will duly email me about tomorrow...:) I have parts 1-10 set aside and will apply any that don't get picked up directly by the maintainers involved.
Yeah, new warnings are unavoidable, as new patches may be introducing extra issues. Hopefully, the new warning will help people to detect the issue earlier before submitting upstream.
Thanks,
Mauro
Jonathan Corbet
maintainerQuoted 12 lines · On Thu, 14 Jan 2021 09:04:36 +0100 Mauro Carvalho Chehab…
1) 10 remaining fixup patches from the series I sent back on Dec, 1st:
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
firmware: stratix10-svc: fix kernel-doc markups
connector: fix a kernel-doc markup
lib/crc7: fix a kernel-doc markup
memblock: fix kernel-doc markups
w1: fix a kernel-doc markup
selftests:kselftest_harness.h: partially fix kernel-doc markups
A week later none of these have shown up in linux-next, so I went ahead and applied the set.
Thanks,
jon
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel