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

Replace HTTP links with HTTPS ones: documentation

2020-06-08T15:30:19Z

Rationale: Reduces attack surface on kernel devs opening the links for MITM as HTTPS traffic is much harder to manipulate. Deterministic algorithm: For each file: For each line: If doesn't contain `\bxmlns\b`: For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`: If both the HTTP and HTTPS versions return 200 OK and serve the same content: Replace HTTP with HTTPS. Signed-off-by: Alexander A. Klimov Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de Signed-off-by: Jonathan Corbet

scripts: kernel-doc: accept blank lines on parameter description

2020-04-20T21:35:58Z

Sphinx is very pedantic with respect to blank lines. Sometimes, in order to make it to properly handle something, we need to add a blank line. However, currently, any blank line inside a kernel-doc comment like: /* * @foo: bar * * foobar * * some description will be considered as if "foobar" was part of the description. This patch changes kernel-doc behavior. After it, foobar will be considered as part of the parameter text. The description will only be considered as such if it starts with: zero spaces after asterisk: *foo one space after asterisk: * foo or have a explicit Description section: * Description: Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: kernel-doc: accept negation like !@var

2020-04-20T21:35:58Z

On a few places, it sometimes need to indicate a negation of a parameter, like: !@fshared This pattern happens, for example, at: kernel/futex.c and it is perfectly valid. However, kernel-doc currently transforms it into: !**fshared** This won't do what it would be expected. Fortunately, fixing the script is a simple matter of storing the "!" before "@" and adding it after the bold markup, like: **!fshared** Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts: kernel-doc: proper handle @foo->bar()

2020-04-20T21:35:58Z

The pattern @foo->bar() is valid, as it can be used by a function pointer inside a struct passed as a parameter. Right now, it causes a warning: ./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string. In this specific case, the kernel-doc markup is: /** * fw_core_remove_address_handler() - unregister an address handler * @handler: callback * * To be called in process context. * * When fw_core_remove_address_handler() returns, @handler->callback() is * guaranteed to not run on any CPU anymore. */ With seems valid on my eyes. So, instead of trying to hack the kernel-doc markup, let's teach it about how to handle such things. This should likely remove lots of other similar warnings as well. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: Add missing close-paren in c:function directives

2020-04-15T20:58:12Z

When kernel-doc generates a 'c:function' directive for a function one of whose arguments is a function pointer, it fails to print the close-paren after the argument list of the function pointer argument. For instance: long work_on_cpu(int cpu, long (*fn) (void *, void * arg) in driver-api/basics.html is missing a ')' separating the "void *" of the 'fn' arguments from the ", void * arg" which is an argument to work_on_cpu(). Add the missing close-paren, so that we render the prototype correctly: long work_on_cpu(int cpu, long (*fn)(void *), void * arg) (Note that Sphinx stops rendering a space between the '(fn*)' and the '(void *)' once it gets something that's syntactically valid.) Signed-off-by: Peter Maydell Link: https://lore.kernel.org/r/20200414143743.32677-1-peter.maydell@linaro.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: Add support for named variable macro arguments

2019-11-07T20:17:24Z

Currently, when kernel-doc encounters a macro with a named variable argument[1], such as this: #define hlist_for_each_entry_rcu(pos, head, member, cond...) ... it expects the variable argument to be documented as `cond...`, rather than `cond`. This is semantically wrong, because the name (as used in the macro body) is actually `cond`. With this patch, kernel-doc will accept the name without dots (`cond` in the example above) in doc comments, and warn if the name with dots (`cond...`) is used and verbose mode[2] is enabled. The support for the `cond...` syntax can be removed later, when the documentation of all such macros has been switched to the new syntax. Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few changes in log output and HTML output: 1) The following warnings[3] are eliminated: ./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu' 2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the correct description is shown 3) Named variable arguments are shown without dots [1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html [2]: scripts/kernel-doc -v [3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c Signed-off-by: Jonathan Neuschäfer Tested-by: Paul E. McKenney Signed-off-by: Jonathan Corbet

kernel-doc: add support for ____cacheline_aligned_in_smp attribute

2019-10-01T12:57:17Z

Subroutine dump_struct uses type attributes to check if the struct syntax is valid. Then, it removes all attributes before using it for output. `____cacheline_aligned_in_smp` is an attribute that is not included in both steps. Add it, since it is used by kernel structs. Signed-off-by: André Almeida Signed-off-by: Jonathan Corbet

kernel-doc: fix processing nested structs with attributes

2019-10-01T12:57:12Z

The current regular expression for strip attributes of structs (and for nested ones as well) also removes all whitespaces that may surround the attribute. After that, the code will split structs and iterate for each symbol separated by comma at the end of struct definition (e.g. "} alias1, alias2;"). However, if the nested struct does not have any alias and has an attribute, it will result in a empty string at the closing bracket (e.g "};"). This will make the split return nothing and $newmember will keep uninitialized. Fix that, by ensuring that the attribute substitution will leave at least one whitespace. Signed-off-by: André Almeida Signed-off-by: Jonathan Corbet

kernel-doc: Allow anonymous enum

2019-08-12T21:00:37Z

In C is a valid construction to have an anonymous enumerator. Though we have now: drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum! Support it in the kernel-doc script. Signed-off-by: Andy Shevchenko Signed-off-by: Jonathan Corbet

kernel-doc: ignore __printf attribute

2019-08-06T17:22:47Z

Ignore __printf() function attributes just as other __attribute__ strings are ignored. Fixes this kernel-doc warning message: include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf' Reported-by: kbuild test robot Signed-off-by: Randy Dunlap Cc: Brendan Higgins Tested-by: Brendan Higgins Signed-off-by: Jonathan Corbet