summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
AgeCommit message (Collapse)Author
2020-10-15scripts: kernel-doc: try to use c:function if possibleMauro Carvalho Chehab
There are a few namespace clashes by using c:macro everywhere: basically, when using it, we can't have something like: .. c:struct:: pwm_capture .. c:macro:: pwm_capture So, we need to use, instead: .. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout) for the function declaration. The kernel-doc change was proposed by Jakob Lykke Andersen here: https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65 Although I did a different implementation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: fix line number handlingMauro Carvalho Chehab
Address several issues related to pointing to the wrong line number: 1) ensure that line numbers will always be initialized When section is the default (Description), the line number is not initializing, producing this: $ ./scripts/kernel-doc --enable-lineno ./drivers/media/v4l2-core/v4l2-mem2mem.c|less **Description** #define LINENO 0 In case of streamoff or release called on any context, 1] If the context is currently running, then abort job will be called 2] If the context is queued, then the context will be removed from the job_queue Which is not right. Ensure that the line number will always be there. After applied, the result now points to the right location: **Description** #define LINENO 410 In case of streamoff or release called on any context, 1] If the context is currently running, then abort job will be called 2] If the context is queued, then the context will be removed from the job_queue 2) The line numbers for function prototypes are always + 1, because it is taken at the line after handling the prototype. Change the logic to point to the next line after the /** */ block; 3) The "DOC:" line number should point to the same line as this markup is found, and not to the next one. Probably part of the issues were due to a but that was causing the line number offset to be incremented by one, if --export were used. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: allow passing desired Sphinx C domain dialectMauro Carvalho Chehab
When kernel-doc is called via kerneldoc.py, there's no need to auto-detect the Sphinx version, as the Sphinx module already knows it. So, add an optional parameter to allow changing the Sphinx dialect. As kernel-doc can also be manually called, keep the auto-detection logic if the parameter was not specified. On such case, emit a warning if sphinx-build can't be found at PATH. I ended using a suggestion from Joe for using a more readable regex, instead of using a complex one with a hidden group like: m/^(\d+)\.(\d+)(?:\.?(\d+)?)/ in order to get the optional <patch> argument. Thanks-to: Joe Perches <joe@perches.com> Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: don't mangle with parameter listMauro Carvalho Chehab
While kernel-doc needs to parse parameters in order to identify its name, it shouldn't be touching the type, as parsing it is very difficult, and errors happen. One current error is when parsing this parameter: const u32 (*tab)[256] Found at ./lib/crc32.c, on this function: u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial); The current logic mangles it, producing this output: const u32 ( *tab That's something that it is not recognizeable. So, instead, let's push the argument as-is, and use it when printing the function prototype and when describing each argument. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: fix typedef identificationMauro Carvalho Chehab
Some typedef expressions are output as normal functions. As we need to be clearer about the type with Sphinx 3.x, detect such cases. While here, fix a wrongly-indented block. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: reimplement -nofunction argumentMauro Carvalho Chehab
Right now, the build system doesn't use -nofunction, as it is pretty much useless, because it doesn't consider the other output modes (extern, internal), working only with all. Also, it is limited to exclude functions. Re-implement it in order to allow excluding any symbols from the document output, no matter what mode is used. The parameter was also renamed to "-nosymbol", as it express better its meaning. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: fix troubles with line countsMauro Carvalho Chehab
There's currently a bug with the way kernel-doc script counts line numbers that can be seen with: $ ./scripts/kernel-doc -rst -enable-lineno include/linux/math64.h >all && ./scripts/kernel-doc -rst -internal -enable-lineno include/linux/math64.h >int && diff -U0 int all --- int 2020-09-28 12:58:08.927486808 +0200 +++ all 2020-09-28 12:58:08.905486845 +0200 @@ -1 +1 @@ -#define LINENO 27 +#define LINENO 26 @@ -3 +3 @@ -#define LINENO 16 +#define LINENO 15 @@ -9 +9 @@ -#define LINENO 17 +#define LINENO 16 ... This is happening with perl version 5.30.3, but I'm not so sure if this is a perl bug, or if this is due to something else. In any case, fixing it is easy. Basically, when "-internal" parameter is used, the process_export_file() function opens the handle "IN". This makes the line number to be incremented, as the handler for the main open is also "IN". Fix the problem by using a different handler for the main open(). While here, add a missing close for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.xMauro Carvalho Chehab
Unfortunately, Sphinx 3.x parser for c functions is too pedantic: https://github.com/sphinx-doc/sphinx/issues/8241 While it could be relaxed with some configurations, there are several corner cases that it would make it hard to maintain, and will require teaching conf.py about several macros. So, let's instead use the :c:macro notation. This will produce an output that it is not as nice as currently, but it should still be acceptable, and will provide cross-references, removing thousands of warnings when building with newer versions of Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: make it more compatible with Sphinx 3.xMauro Carvalho Chehab
With Sphinx 3.x, the ".. c:type:" tag was changed to accept either: .. c:type:: typedef-like declaration .. c:type:: name Using it for other types (including functions) don't work anymore. So, there are newer tags for macro, enum, struct, union, and others, which doesn't exist on older versions. Add a check for the Sphinx version and change the produced tags accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15scripts: kernel-doc: add support for typedef enumMauro Carvalho Chehab
The PHY kernel-doc markup has gained support for documenting a typedef enum. However, right now the parser was not prepared for it. So, add support for parsing it. Fixes: 4069a572d423 ("net: phy: Document core PHY structures") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-09-16kernel-doc: add support for ____cacheline_aligned attributeJonathan Cameron
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` is an attribute that is not included in both steps. Add it, since it is used by kernel structs. Based on previous patch to add ____cacheline_aligned_in_smp. Motivated by patches to reorder this attribute to before the variable name. Whilst we could do that in all cases, that would be a massive change and it is more common in the kernel to place this particular attribute after the variable name. A quick grep suggests approximately 400 instances of which 341 have this attribute just before a semicolon and hence after the variable name. Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Cc: Lee Jones <lee.jones@linaro.org> Link: https://lore.kernel.org/r/20200910185415.653139-1-jic23@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-09-10kernel-doc: include line numbers for function prototypesMauro Carvalho Chehab
This should solve bad error reports like this one: ./include/linux/iio/iio.h:0: WARNING: Unknown target name: "devm". Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/56eed0ba50cd726236acd12b11b55ce54854c5ea.1599660067.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-07-31scripts/kernel-doc: optionally treat warnings as errorsPierre-Louis Bossart
The kbuild bot recently added the W=1 option, which triggered documentation cleanups to squelch hundreds of kernel-doc warnings. To make sure new kernel contributions don't add regressions to kernel-doc descriptors, this patch suggests an option to treat warnings as errors in CI/automated tests. A -Werror command-line option is added to the kernel-doc script. When this option is set, the script will return the number of warnings found. The caller can then treat this positive return value as an error and stop the build. Using this command line option is however not straightforward when the kernel-doc script is called from other scripts. To align with typical kernel compilation or documentation generation, the Werror option is also set by checking the KCFLAGS environment variable, or if KDOC_WERROR is defined, as in the following examples: KCFLAGS="-Wall -Werror" make W=1 sound/ KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/ KDOC_WERROR=1 make htmldocs Note that in the last example the documentation build does not stop, only an additional log is provided. Credits to Randy Dunlap for suggesting the use of environment variables. Suggested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-26scripts/kernel-doc: handle function pointer prototypesMauro Carvalho Chehab
There are some function pointer prototypes inside the net includes, like this one: int (*pcs_config)(struct phylink_config *config, unsigned int mode, phy_interface_t interface, const unsigned long *advertising); There's nothing wrong using it with kernel-doc, but we need to add a rule for it to parse such kind of prototype. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/fec520dd731a273013ae06b7653a19c7d15b9562.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-26scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASKMauro Carvalho Chehab
The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of DECLARE_BITMAP(), used by phylink.h. As we have already a parser for DECLARE_BITMAP(), let's add one for this macro, in order to avoid such warnings: ./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising' not described in 'phylink_link_state' ./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising' not described in 'phylink_link_state' Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/d1d1dea67a28117c0b0c33271b139c4455fef287.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-08Replace HTTP links with HTTPS ones: documentationAlexander A. Klimov
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 <grandmaster@al2klimov.de> Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20scripts: kernel-doc: accept blank lines on parameter descriptionMauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20scripts: kernel-doc: accept negation like !@varMauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20scripts: kernel-doc: proper handle @foo->bar()Mauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-15scripts/kernel-doc: Add missing close-paren in c:function directivesPeter Maydell
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 <peter.maydell@linaro.org> Link: https://lore.kernel.org/r/20200414143743.32677-1-peter.maydell@linaro.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-11-07scripts/kernel-doc: Add support for named variable macro argumentsJonathan Neuschäfer
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 <j.neuschaefer@gmx.net> Tested-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-01kernel-doc: add support for ____cacheline_aligned_in_smp attributeAndré Almeida
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 <andrealmeid@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-01kernel-doc: fix processing nested structs with attributesAndré Almeida
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 <andrealmeid@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-12kernel-doc: Allow anonymous enumAndy Shevchenko
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 <andriy.shevchenko@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-06kernel-doc: ignore __printf attributeRandy Dunlap
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 <lkp@intel.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Brendan Higgins <brendanhiggins@google.com> Tested-by: Brendan Higgins <brendanhiggins@google.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26kernel-doc: Don't try to mark up function namesJonathan Corbet
We now have better automarkup in sphinx itself and, besides, this markup was incorrect and left :c:func: gunk in the processed docs. Sort of discouraging that nobody ever noticed...:) As a first step toward the removal of impenetrable regex magic from kernel-doc it's a tiny one, but you have to start somewhere. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-27kernel-doc: always name missing kerneldoc sectionsJonathan Corbet
The "no structured comments found" warning is not particularly useful if there are several invocations, one of which is looking for something wrong. So if something specific has been requested, make it clear that it's the one we weren't able to find. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-16kernel-doc: suppress 'not described' warnings for embedded struct fieldsJonathan Corbet
The ability to add kerneldoc comments for fields in embedded structures is useful, but it brought along a whole bunch of warnings for fields that could not be described before. In many cases, there's little value in adding docs for these nested fields, and in cases like: struct a { struct b { int c; } d, e; }; "c" would have to be described twice (as d.c and e.c) to make the warnings go away. We can no doubt do something smarter, but simply suppressing the warnings for this case removes about 70 warnings from the docs build, freeing us to focus on the ones that matter more. So make kerneldoc be silent about missing descriptions for any field containing a ".". Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-25scripts/kernel-doc: Fix struct and struct field attribute processingSakari Ailus
The kernel-doc attempts to clear the struct and struct member attributes from the API documentation it produces. It falls short of the job in the following respects: - extra whitespaces are left where __attribute__((...)) was removed, - only a single attribute is removed per struct, - attributes (such as aligned) containing numbers were not removed, - attributes are only cleared from struct fields, not structs themselves. This patch addresses these issues by removing the attributes. Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-07kernel-doc: extend $type_param to match members referenced by pointerMike Rapoport
Currently, function parameter description can match '@type.member' expressions but fails to match '@type->member'. Extend the $type_param regex to allow matching both Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-07kernel-doc: kill trailing whitespaceMike Rapoport
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-18kernel-doc: fix declaration type determinationRandy Dunlap
Make declaration type determination more robust. When scripts/kernel-doc is deciding if some kernel-doc notation contains an enum, a struct, a union, a typedef, or a function, it does a pattern match on the beginning of the string, looking for a match with one of "struct", "union", "enum", or "typedef", and otherwise defaults to a function declaration type. However, if a function or a function-like macro has a name that begins with "struct" (e.g., struct_size()), then kernel-doc incorrectly decides that this is a struct declaration. Fix this by looking for the declaration type keywords having an ending word boundary (\b), so that "struct_size" will not match a struct declaration. I compared lots of html before/after output from core-api, driver-api, and networking. There were no differences in any of the files that I checked. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-08-06scripts/kernel-doc: Escape all literal braces in regexesBen Hutchings
Commit 701b3a3c0ac4 ("PATCH scripts/kernel-doc") fixed the two instances of literal braces that Perl 5.28 warns about, but there are still more than it doesn't warn about. Escape all left braces that are treated as literal characters. Also escape literal right braces, for consistency and to avoid confusing bracket-matching in text editors. Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-07-23PATCH scripts/kernel-docvaldis.kletnieks@vt.edu
Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions" Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE [^\{\}]*})/ at ./scripts/kernel-doc line 1155. Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE )/ at ./scripts/kernel-doc line 1179. Signed-off-by: Valdis Kletnieks <valdis.kletnieks@vt.edu> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-29docs: kernel-doc: fix parsing of arraysMauro Carvalho Chehab
The logic with parses array has a bug that prevents it to parse arrays like: struct { ... struct { u64 msdu[IEEE80211_NUM_TIDS + 1]; ... ... Fix the parser to accept it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-21kernel-doc: Remove __sched markingsMatthew Wilcox
I find the __sched annotations unaesthetic in the kernel-doc. Remove them like we remove __inline, __weak, __init and so on. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-20Merge branch 'kerneldoc2' into docs-nextJonathan Corbet
So once upon a time I set out to fix the problem reported by Tobin wherein a literal block within a kerneldoc comment would be corrupted in processing. On the way, though, I got annoyed at the way I have to learn how kernel-doc works from the beginning every time I tear into it. As a result, seven of the following eight patches just get rid of some dead code and reorganize the rest - mostly turning the 500-line process_file() function into something a bit more rational. Sphinx output is unchanged after these are applied. Then, at the end, there's a tweak to stop messing with literal blocks. If anybody was unaware that I've not done any serious Perl since the 1990's, they will certainly understand that fact now.
2018-02-20docs: Add an SPDX header to kernel-docJonathan Corbet
Add the SPDX header while I'm in the neighborhood. The source itself just says "GNU General Public License", but it also refers people to the COPYING file for further information. Since COPYING says 2.0-only, that is what I have put into the header. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18scripts: kernel-doc: support in-line comments on nested structs/unionsMauro Carvalho Chehab
The parser at kernel-doc rejects names with dots in the middle. Fix it, in order to support nested structs/unions. Tested-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18scripts: kernel_doc: fixup reporting of function identifiersMike Rapoport
When function description includes brackets after the function name as suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script omits the function name from "Scanning doc for" report. Extending match for identifier name with optional brackets fixes this issue. Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Don't mangle literal code blocks in commentsJonathan Corbet
It can be useful to put code snippets into kerneldoc comments; that can be done with the "::" operator at the end of a line like this:: if (desperate) run_in_circles(); The ".. code-block::" directive can also be used to this end. kernel-doc currently fails to understand these literal blocks and applies its normal markup to them, which is then treated as literal by sphinx. The result is unsightly markup instead of a useful code snippet. Apply a hack to the output code to recognize literal blocks and avoid performing any special markup on them. It's ugly, but that means it fits in well with the rest of the script. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Finish moving STATE_* code out of process_file()Jonathan Corbet
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now actually fits on a single screen. Delete an unused variable and add a couple of comments while I'm at it. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_PROTO processing into its own functionJonathan Corbet
Move the top-level prototype-processing code out of process_file(). Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_BODY processing to a separate functionJonathan Corbet
Also group the pseudo-global $leading_space variable with its peers. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_NAME processing into its own functionJonathan Corbet
Move this code out of process_file() in the name of readability and maintainability. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_NORMAL processing into its own functionJonathan Corbet
Begin the process of splitting up the nearly 500-line process_file() function by moving STATE_NORMAL processing to a separate function. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Rename and split STATE_FIELDJonathan Corbet
STATE_FIELD describes a parser state that can handle any part of a kerneldoc comment body; rename it to STATE_BODY to reflect that. The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of it and make a proper state (STATE_BODY_MAYBE) instead. This will make the subsequent process_file() splitup easier. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Get rid of xml_escape() and friendsJonathan Corbet
XML escaping is a worry that came with DocBook, which we no longer have any dealings with. So get rid of the useless xml_escape()/xml_unescape() functions. No change to the generated output. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-01-01scripts: kernel_doc: better handle show warnings logicMauro Carvalho Chehab
The logic with inhibits warnings for definitions that is not output is incomplete: it doesn't cover the cases where OUTPUT_INTERNAL and OUTPUT_EXPORTED are used. As the most common case is OUTPUT_ALL, place it first, in order to optimize a litte bit the check logic. Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings") Reported-by: Randy Dunlap <rdunlap@infradead.org> Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: apply filtering rules to warningsMauro Carvalho Chehab
When kernel-doc is called with output selection filters, it will be called lots of time for a single file. If there is a warning present there, it means that it may print hundreds of identical warnings. Worse than that, the -function NAME actually filters only functions. So, it makes no sense at all to print warnings for structs or enums. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>