lwn.git/scripts/kernel-doc, branch docs-5.16

kernel-doc: support DECLARE_PHY_INTERFACE_MASK()

2021-11-01T17:28:35+00:00

Support the DECLARE_PHY_INTERFACE_MASK() macro that is used to declare a bitmap by converting the macro to DECLARE_BITMAP(), as has been done for the __ETHTOOL_DECLARE_LINK_MODE_MASK() macro. This fixes a 'make htmldocs' warning: include/linux/phylink.h:82: warning: Function parameter or member 'DECLARE_PHY_INTERFACE_MASK(supported_interfaces' not described in 'phylink_config' that was introduced by commit 38c310eb46f5 ("net: phylink: add MAC phy_interface_t bitmap") Signed-off-by: Randy Dunlap Reported-by: Stephen Rothwell Cc: Russell King (Oracle) Link: https://lore.kernel.org/r/45934225-7942-4326-f883-a15378939db9@infradead.org Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Ignore __alloc_size() attribute

2021-10-12T20:11:06+00:00

Fixes "Compiler Attributes: add __alloc_size() for better bounds checking" so that the __alloc_size() macro is ignored for function prototypes when generating kerndoc. Avoids warnings like: ./include/linux/slab.h:662: warning: Function parameter or member '1' not described in '__alloc_size' ./include/linux/slab.h:662: warning: Function parameter or member '2' not described in '__alloc_size' ./include/linux/slab.h:662: warning: expecting prototype for kcalloc(). Prototype was for __alloc_size() instead Suggested-by: Matthew Wilcox Reported-by: Stephen Rothwell Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20211011180650.3603988-1-keescook@chromium.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: Override -Werror from KCFLAGS with KDOC_WERROR

2021-08-12T14:58:13+00:00

Since commit 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors"), the kernel-doc script will treat warnings as errors when one of the following conditions is true: - The KDOC_WERROR environment variable is non-zero - The KCFLAGS environment variable contains -Werror - The -Werror parameter is passed to kernel-doc Checking KCFLAGS for -Werror allows piggy-backing on the C compiler error handling. However, unlike the C compiler, kernel-doc has no provision for -Wno-error. This makes compiling the kernel with -Werror (to catch regressions) and W=1 (to enable more checks) always fail, without the same possibility as offered by the C compiler to treating some selected warnings as warnings despite the global -Werror setting. To fix this, evaluate KDOC_WERROR after KCFLAGS, which allows disabling the warnings-as-errors behaviour of kernel-doc selectively by setting KDOC_WERROR=0. Signed-off-by: Laurent Pinchart Link: https://lore.kernel.org/r/20210730225401.4401-1-laurent.pinchart+renesas@ideasonboard.com Signed-off-by: Jonathan Corbet

scripts: kernel-doc: reduce repeated regex expressions into variables

2021-05-17T17:21:16+00:00

There are some regex expressions in the kernel-doc script, which are used repeatedly in the script. Reduce such expressions into variables, which can be used everywhere. A quick manual check found that no errors and warnings were added/removed in this process. Suggested-by: Jonathan Corbet Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210514144244.25341-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet

kernel-doc: Add support for __deprecated

2021-04-27T15:59:04+00:00

The current linux-next tree has a new error: ./Documentation/gpu/drm-mm:445: ./drivers/gpu/drm/drm_prime.c:994: WARNING: Error in declarator or parameters Invalid C declaration: Expecting "(" in parameters. [error at 17] int __deprecated drm_prime_sg_to_page_array (struct sg_table *sgt, struct page **pages, int max_entries) -----------------^ While we might consider that documenting a deprecated interface is not necessarily best practice, removing the error is easy. Signed-off-by: Matthew Wilcox (Oracle) Link: https://lore.kernel.org/r/20210427114828.GY235567@casper.infradead.org Signed-off-by: Jonathan Corbet

scripts: kernel-doc: improve parsing for kernel-doc comments syntax

2021-04-15T21:26:06+00:00

Currently kernel-doc does not identify some cases of probable kernel doc comments, for e.g. pointer used as declaration type for identifier, space separated identifier, etc. Some example of these cases in files can be: i)" * journal_t * jbd2_journal_init_dev() - creates and initialises a journal structure" in fs/jbd2/journal.c ii) "* dget, dget_dlock - get a reference to a dentry" in include/linux/dcache.h iii) " * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t" in include/linux/seqlock.h Also improve identification for non-kerneldoc comments. For e.g., i) " * The following functions allow us to read data using a swap map" in kernel/power/swap.c does follow the kernel-doc like syntax, but the content inside does not adheres to the expected format. Improve parsing by adding support for these probable attempts to write kernel-doc comment. Suggested-by: Jonathan Corbet Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com [ jc: fixed some line-length issues ] Signed-off-by: Jonathan Corbet

scripts: kernel-doc: add warning for comment not following kernel-doc syntax

2021-03-29T23:08:28+00:00

Currently, kernel-doc start parsing the comment as a kernel-doc comment if it starts with '/**', but does not take into account if the content inside the comment too, adheres with the expected format. This results in unexpected and unclear warnings for the user. E.g., running scripts/kernel-doc -none mm/memcontrol.c emits: "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead" Here kernel-doc parses the corresponding comment as a kernel-doc comment and expects prototype for it in the next lines, and as a result causing this warning. Provide a clearer warning message to the users regarding the same, if the content inside the comment does not follow the kernel-doc expected format. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet

docs: kernel-doc: properly recognize parameter lines with colons

2021-03-26T19:16:35+00:00

The previous attempt to properly handle literal blocks broke parsing of parameter lines containing colons; fix it by tweaking the regex to specifically exclude the "::" pattern while accepting lines containing colons in general. Add a little documentation to the regex while in the neighborhood. Reported-by: Stephen Rothwell Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences") Signed-off-by: Jonathan Corbet

kernel-doc: better handle '::' sequences

2021-03-25T18:50:27+00:00

Right now, if one of the following headers end with a '::', the kernel-doc script will do the wrong thing: description|context|returns?|notes?|examples? The real issue is with examples, as people could try to write something like: example:: /* Some C code */ and this won't be properly evaluated. So, improve the regex to not catch '\w+::' regex for the above identifiers. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: ignore identifier on anonymous enums

2021-03-09T00:10:24+00:00

When anonymous enums are used, the identifier is empty. While, IMO, it should be avoided the usage of such enums, adding support for it is not hard. So, postpone the check for empty identifiers to happen only at the dump phase. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/055ad57879f1b9381b90879e00f72fde1c3a5647.1614760910.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet