user/sven/linux.git/scripts/kernel-doc, branch v5.15.8

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

2021-08-12T14:58:13Z

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:16Z

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:04Z

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:06Z

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:28Z

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:35Z

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:27Z

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:24Z

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

scripts: kernel-doc: fix attribute capture in function parsing

2021-03-08T23:04:20Z

Currently, kernel-doc warns for function prototype parsing on the presence of attributes "__attribute_const__" and "__flatten" in the definition. There are 166 occurrences in ~70 files in the kernel tree for "__attribute_const__" and 5 occurrences in 4 files for "__flatten". Out of 166, there are 3 occurrences in three different files with "__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in ./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other occurrences have no preceding kernel-doc. Add support for "__attribute_const__" and "__flatten" attributes. A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals that no additional warning or error has been added or removed by the fix. Suggested-by: Lukas Bulwahn Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210306113510.31023-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet

scripts: kernel-doc: fix typedef support for struct/union parsing

2021-03-07T00:36:51Z

Currently, there are ~1290 occurrences in 447 files in the kernel tree 'typedef struct/union' syntax for defining some struct/union. However, kernel-doc currently does not support that syntax. Of the ~1290 occurrences, there are four occurrences in ./include/linux/zstd.h with typedef struct/union syntax and a preceding kernel-doc; all other occurrences have no preceding kernel-doc. Add support for parsing struct/union following this syntax. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210225145033.11431-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet