- Jul 04, 2023
-
-
Jakub Kicinski authored
Enums benefit from private markings, too. For netlink attribute name enums always end with a pair of __$n_MAX and $n_MAX members. Documenting them feels a bit tedious. Signed-off-by:
Jakub Kicinski <kuba@kernel.org> Reviewed-by:
Randy Dunlap <rdunlap@infradead.org> Tested-by:
Jonathan Corbet <corbet@lwn.net> Message-ID: <20230621223525.2722703-1-kuba@kernel.org>
-
- Jun 10, 2023
-
-
Johannes Berg authored
The kernel-doc script currently reports a number of issues only in "verbose" mode, but that's initialized from V=1 (via KBUILD_VERBOSE), so if you use KDOC_WERROR=1 then adding V=1 might actually break the build. This is rather unexpected. Change kernel-doc to not change its behaviour wrt. errors (or warnings) when verbose mode is enabled, but rather add separate warning flags (and -Wall) for it. Allow enabling those flags via environment/make variables in the kernel's build system for easier user use, but to not have to parse them in the script itself. Signed-off-by:
Johannes Berg <johannes.berg@intel.com> Acked-by:
Masahiro Yamada <masahiroy@kernel.org>
-
- Jun 05, 2023
-
-
Mark Rutland authored
In some cases we'd like to indicate the bitwise negation of a parameter, e.g. ~@var This will be helpful for describing the atomic andnot operations, where we'd like to write comments of the form: Atomically updates @v to (@v & ~@i) Which kernel-doc currently transforms to: Atomically updates **v** to (**v** & ~**i**) Rather than the preferable form: Atomically updates **v** to (**v** & **~i**) This is similar to what we did for '!@var' in commit: ee2aa759 ("scripts: kernel-doc: accept negation like !@var") This patch follows the same pattern that commit used to permit a '!' prefix on a param ref, allowing a '~' prefix on a param ref, cuasing kernel-doc to generate the preferred form above. Suggested-by:
Akira Yokosawa <akiyks@gmail.com> Signed-off-by:
Mark Rutland <mark.rutland@arm.com> Signed-off-by:
Peter Zijlstra (Intel) <peterz@infradead.org> Link: https://lore.kernel.org/r/20230605070124.3741859-25-mark.rutland@arm.com
-
- Jan 31, 2023
-
-
Jonathan Neuschäfer authored
Commit 43756e34 ("scripts/kernel-doc: Add support for named variable macro arguments") improved how named variable macro arguments are handled, and changed how they are documented in kerneldoc comments from "@param...", to "@param", deprecating the old syntax. All users of the old syntax have since been converted, so this commit finally removes support for it. The output of "make htmldocs" is the same with and without this commit. Signed-off-by:
Jonathan Neuschäfer <j.neuschaefer@gmx.net> Link: https://lore.kernel.org/r/20230129150435.1510400-1-j.neuschaefer@gmx.net Signed-off-by:
-
- Jan 22, 2023
-
-
Masahiro Yamada authored
Some scripts increase the verbose level when V=1, but others when not V=0. I think the former is correct because V=2 is not a log level but a switch to print the reason for rebuilding. Signed-off-by:
Nicolas Schier <nicolas@fjasle.eu>
-
- Nov 29, 2022
-
-
Jason Gunthorpe authored
Parse EXPORT_SYMBOL_NS_GPL() in addition to EXPORT_SYMBOL_GPL() for use with the -export flag. Link: https://lore.kernel.org/r/4-v6-a196d26f289e+11787-iommufd_jgg@nvidia.com Acked-by:
Jason Gunthorpe <jgg@nvidia.com>
-
- Oct 28, 2022
-
-
Kees Cook authored
While there were varying degrees of kern-doc for various str*()-family functions, many needed updating and clarification, or to just be entirely written. Update (and relocate) existing kern-doc and add missing functions, sadly shaking my head at how many times I have written "Do not use this function". Include the results in the core kernel API doc. Cc: Bagas Sanjaya <bagasdotme@gmail.com> Cc: Andy Shevchenko <andy@kernel.org> Cc: Rasmus Villemoes <linux@rasmusvillemoes.dk> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: linux-hardening@vger.kernel.org Tested-by:
Kees Cook <keescook@chromium.org>
-
- Oct 18, 2022
-
-
Jonathan Corbet authored
Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by:
Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by:
-
- Jun 13, 2022
-
-
Niklas Söderlund authored
Some warnings do not increment the warnings counter making the behavior of running kernel-doc with -Werror unlogical as some warnings will be generated but not treated as errors. Fix this by creating a helper function that always incrementing the warnings counter every time a warning is emitted. There is one location in get_sphinx_version() where a warning is not touched as it concerns the execution environment of the kernel-doc and not the documentation being processed. Incrementing the counter only have effect when running kernel-doc in either verbose mode (-v or environment variable KBUILD_VERBOSE) or when treating warnings as errors (-Werror or environment variable KDOC_WERROR). In both cases the number of warnings printed is printed to stderr and for the later the exit code of kernel-doc is non-zero if warnings where encountered. Simple test case to demo one of the warnings, $ cat test.c /** * foo() - Description */ int bar(); # Without this change $ ./scripts/kernel-doc -Werror -none test.c test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead # With this change $ ./scripts/kernel-doc -Werror -none test.c test.c:4: warning: expecting prototype for foo(). Prototype was for bar() instead 1 warnings as Errors Signed-off-by:Niklas Söderlund <niklas.soderlund@corigine.com> Link: https://lore.kernel.org/r/20220613090510.3088294-1-niklas.soderlund@corigine.com Signed-off-by:
-
- Mar 28, 2022
-
-
Mauro Carvalho Chehab authored
In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by:
-
- Feb 24, 2022
-
-
Akira Yokosawa authored
Currently, when there is no FILE argument following a switch such as -man, -rst, or -none, kernel-doc exits with a warning from perl (long msg folded): Use of uninitialized value $ARGV[0] in pattern match (m//) at ./scripts/kernel-doc line 438. , which is unhelpful. Improve the behavior by adding a check at the bottom of parsing loop. If the argument is absent, display help text and exit with the code of 1 (via usage()). Signed-off-by: -
Tomasz Warniełło authored
I wanted to clean up these lines, but in the end decided not to touch the old ones and just add my own about POD. I'll leave the cleanup for lawyers. Signed-off-by:
Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by:
-
Tomasz Warniełło authored
What for? To improve the script maintainability. 1. License As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is enough. 2. The to-do list comment As suggested by Jonathan Corbet in reply to my version 3, this section doesn't need to be transitioned. And so it is removed for clarity. 3. The historical changelog comments As suggested by Jonathan Corbet in a reply to v3, this section can go. I wanted to keep it, but since it doesn't contain copyright notices, let's just have it clean and simple. 4. The "format of comments" comment block As suggested by Jani Nikula in a reply to my first version of this transformation, Documentation/doc-guide/kernel-doc.rst can serve as the information hub for comment formatting. The section DESCRIPTION already points there, so the original comment block can just be removed. Suggested-by:
Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured You can see the results with: $ scripts/kernel-doc -help Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured Notes: - The -help token is added. - The entries are sorted alphbetically. Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured A subsection "reStructuredText only" is added for -enable-lineno. Other notes: - paragraphing correction Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured The plurals in -function and -nosymbol are corrected to singulars. That's how the script works now. I think this describes the syntax better. The plurar suggests multiple FILE arguments might be possible. So this seems more coherent. Other notes: - paragraphing correction - article correction Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more happy This section is renamed to "Output format modifiers" to make it simple. To make it even more simple, a subsection is added: "reStructuredText only". Other notes: - paragraphing correction - article correction Signed-off-by:
-
Tomasz Warniełło authored
Another step in the direction of a uniform POD documentation, which will make users happier. Options land at the end of the script, not to clutter the file top. The default output format is corrected to rst. That's what it is now. A POD delimiting comment is added to the script head, which improves the script logical structure. Signed-off-by:
-
Tomasz Warniełło authored
Transition the description section into POD. This is one of the standard documentation sections. This adjustment makes the section available for POD and makes it look better. Notes: - an article addition - paragraphing correction Signed-off-by:
-
Tomasz Warniełło authored
The former usage function is substituted, although not as the -h and -help parameter handler yet. Purpose: Use Pod::Usage to handle documentation printing in an integrated way. Signed-off-by:
-
Tomasz Warniełło authored
The NAME section provides the doc title, while SYNOPSIS contains the basic syntax and usage description, which will be printed in the help document and in the error output produced on wrong script usage. The rationale is to give users simple and succinct enlightment, at the same time structuring the script internally for the maintainers. In the synopsis, Rst-only options are grouped around rst, and the rest is arranged as in the OPTIONS subsections (yet to be translated into POD, check at the end of the series). The third of the basic sections, DESCRIPTION, is added separately. Signed-off-by:
-
- Nov 01, 2021
-
-
Randy Dunlap authored
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 38c310eb ("net: phylink: add MAC phy_interface_t bitmap") Signed-off-by:
Stephen Rothwell <sfr@canb.auug.org.au> Cc: Russell King (Oracle) <linux@armlinux.org.uk> Link: https://lore.kernel.org/r/45934225-7942-4326-f883-a15378939db9@infradead.org Signed-off-by:
-
- Oct 18, 2021
-
-
Kees Cook authored
There are many places where kernel code wants to have several different typed trailing flexible arrays. This would normally be done with multiple flexible arrays in a union, but since GCC and Clang don't (on the surface) allow this, there have been many open-coded workarounds, usually involving neighboring 0-element arrays at the end of a structure. For example, instead of something like this: struct thing { ... union { struct type1 foo[]; struct type2 bar[]; }; }; code works around the compiler with: struct thing { ... struct type1 foo[0]; struct type2 bar[]; }; Another case is when a flexible array is wanted as the single member within a struct (which itself is usually in a union). For example, this would be worked around as: union many { ... struct { struct type3 baz[0]; }; }; These kinds of work-arounds cause problems with size checks against such zero-element arrays (for example when building with -Warray-bounds and -Wzero-length-bounds, and with the coming FORTIFY_SOURCE improvements), so they must all be converted to "real" flexible arrays, avoiding warnings like this: fs/hpfs/anode.c: In function 'hpfs_add_sector_to_btree': fs/hpfs/anode.c:209:27: warning: array subscript 0 is outside the bounds of an interior zero-length array 'struct bplus_internal_node[0]' [-Wzero-length-bounds] 209 | anode->btree.u.internal[0].down = cpu_to_le32(a); | ~~~~~~~~~~~~~~~~~~~~~~~^~~ In file included from fs/hpfs/hpfs_fn.h:26, from fs/hpfs/anode.c:10: fs/hpfs/hpfs.h:412:32: note: while referencing 'internal' 412 | struct bplus_internal_node internal[0]; /* (internal) 2-word entries giving | ^~~~~~~~ drivers/net/can/usb/etas_es58x/es58x_fd.c: In function 'es58x_fd_tx_can_msg': drivers/net/can/usb/etas_es58x/es58x_fd.c:360:35: warning: array subscript 65535 is outside the bounds of an interior zero-length array 'u8[0]' {aka 'unsigned char[]'} [-Wzero-length-bounds] 360 | tx_can_msg = (typeof(tx_can_msg))&es58x_fd_urb_cmd->raw_msg[msg_len]; | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In file included from drivers/net/can/usb/etas_es58x/es58x_core.h:22, from drivers/net/can/usb/etas_es58x/es58x_fd.c:17: drivers/net/can/usb/etas_es58x/es58x_fd.h:231:6: note: while referencing 'raw_msg' 231 | u8 raw_msg[0]; | ^~~~~~~ However, it _is_ entirely possible to have one or more flexible arrays in a struct or union: it just has to be in another struct. And since it cannot be alone in a struct, such a struct must have at least 1 other named member -- but that member can be zero sized. Wrap all this nonsense into the new DECLARE_FLEX_ARRAY() in support of having flexible arrays in unions (or alone in a struct). As with struct_group(), since this is needed in UAPI headers as well, implement the core there, with a non-UAPI wrapper. Additionally update kernel-doc to understand its existence. https://github.com/KSPP/linux/issues/137 Cc: Arnd Bergmann <arnd@arndb.de> Cc: "Gustavo A. R. Silva" <gustavoars@kernel.org> Signed-off-by:
-
- Oct 12, 2021
-
-
Kees Cook authored
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 <willy@infradead.org> Reported-by:
-
- Sep 25, 2021
-
-
Kees Cook authored
Kernel code has a regular need to describe groups of members within a structure usually when they need to be copied or initialized separately from the rest of the surrounding structure. The generally accepted design pattern in C is to use a named sub-struct: struct foo { int one; struct { int two; int three, four; } thing; int five; }; This would allow for traditional references and sizing: memcpy(&dst.thing, &src.thing, sizeof(dst.thing)); However, doing this would mean that referencing struct members enclosed by such named structs would always require including the sub-struct name in identifiers: do_something(dst.thing.three); This has tended to be quite inflexible, especially when such groupings need to be added to established code which causes huge naming churn. Three workarounds exist in the kernel for this problem, and each have other negative properties. To avoid the naming churn, there is a design pattern of adding macro aliases for the named struct: #define f_three thing.three This ends up polluting the global namespace, and makes it difficult to search for identifiers. Another common work-around in kernel code avoids the pollution by avoiding the named struct entirely, instead identifying the group's boundaries using either a pair of empty anonymous structs of a pair of zero-element arrays: struct foo { int one; struct { } start; int two; int three, four; struct { } finish; int five; }; struct foo { int one; int start[0]; int two; int three, four; int finish[0]; int five; }; This allows code to avoid needing to use a sub-struct named for member references within the surrounding structure, but loses the benefits of being able to actually use such a struct, making it rather fragile. Using these requires open-coded calculation of sizes and offsets. The efforts made to avoid common mistakes include lots of comments, or adding various BUILD_BUG_ON()s. Such code is left with no way for the compiler to reason about the boundaries (e.g. the "start" object looks like it's 0 bytes in length), making bounds checking depend on open-coded calculations: if (length > offsetof(struct foo, finish) - offsetof(struct foo, start)) return -EINVAL; memcpy(&dst.start, &src.start, offsetof(struct foo, finish) - offsetof(struct foo, start)); However, the vast majority of places in the kernel that operate on groups of members do so without any identification of the grouping, relying either on comments or implicit knowledge of the struct contents, which is even harder for the compiler to reason about, and results in even more fragile manual sizing, usually depending on member locations outside of the region (e.g. to copy "two" and "three", use the start of "four" to find the size): BUILD_BUG_ON((offsetof(struct foo, four) < offsetof(struct foo, two)) || (offsetof(struct foo, four) < offsetof(struct foo, three)); if (length > offsetof(struct foo, four) - offsetof(struct foo, two)) return -EINVAL; memcpy(&dst.two, &src.two, length); In order to have a regular programmatic way to describe a struct region that can be used for references and sizing, can be examined for bounds checking, avoids forcing the use of intermediate identifiers, and avoids polluting the global namespace, introduce the struct_group() macro. This macro wraps the member declarations to create an anonymous union of an anonymous struct (no intermediate name) and a named struct (for references and sizing): struct foo { int one; struct_group(thing, int two; int three, four; ); int five; }; if (length > sizeof(src.thing)) return -EINVAL; memcpy(&dst.thing, &src.thing, length); do_something(dst.three); There are some rare cases where the resulting struct_group() needs attributes added, so struct_group_attr() is also introduced to allow for specifying struct attributes (e.g. __align(x) or __packed). Additionally, there are places where such declarations would like to have the struct be tagged, so struct_group_tagged() is added. Given there is a need for a handful of UAPI uses too, the underlying __struct_group() macro has been defined in UAPI so it can be used there too. To avoid confusing scripts/kernel-doc, hide the macro from its struct parsing. Co-developed-by:Keith Packard <keithp@keithp.com> Signed-off-by:
Gustavo A. R. Silva <gustavoars@kernel.org> Link: https://lore.kernel.org/lkml/20210728023217.GC35706@embeddedor Enhanced-by:
Rasmus Villemoes <linux@rasmusvillemoes.dk> Link: https://lore.kernel.org/lkml/41183a98-bdb9-4ad6-7eab-5a7292a6df84@rasmusvillemoes.dk Enhanced-by:
Dan Williams <dan.j.williams@intel.com> Link: https://lore.kernel.org/lkml/1d9a2e6df2a9a35b2cdd50a9a68cac5991e7e5f0.camel@intel.com Enhanced-by:
Daniel Vetter <daniel.vetter@ffwll.ch> Link: https://lore.kernel.org/lkml/YQKa76A6XuFqgM03@phenom.ffwll.local Acked-by:
-
- Aug 12, 2021
-
-
Laurent Pinchart authored
Since commit 2c12c810 ("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 <laurent.pinchart+renesas@ideasonboard.com> Link: https://lore.kernel.org/r/20210730225401.4401-1-laurent.pinchart+renesas@ideasonboard.com Signed-off-by:
-
- May 17, 2021
-
-
Aditya Srivastava authored
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:
Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210514144244.25341-1-yashsri421@gmail.com Signed-off-by:
-
- Apr 27, 2021
-
-
Matthew Wilcox authored
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:
-
- Apr 15, 2021
-
-
Aditya Srivastava authored
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:
-
- Mar 29, 2021
-
-
Aditya Srivastava authored
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:
-
- Mar 26, 2021
-
-
Jonathan Corbet authored
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:
-
- Mar 25, 2021
-
-
Mauro Carvalho Chehab authored
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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org Signed-off-by:
-
- Mar 09, 2021
-
-
Mauro Carvalho Chehab authored
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:
-
- Mar 08, 2021
-
-
Aditya Srivastava authored
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 <lukas.bulwahn@gmail.com> Signed-off-by:
-
- Mar 07, 2021
-
-
Aditya Srivastava authored
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:
-
- Feb 22, 2021
-
-
Aditya Srivastava authored
Currently, kernel-doc causes an unexpected error when array element (i.e., "type (*foo[bar])(args)") is present as pointer parameter in pointer-to-function parsing. For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this error: "Use of uninitialized value $param in regexp compilation at ...", in combination with: "warning: Function parameter or member '' not described in 'gcov_info'" Here, the parameter parsing does not take into account the presence of array element (i.e. square brackets) in $param. Provide a simple fix by adding square brackets in the regex, responsible for capturing $param. A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree, reveals that no additional warning or error has been added or removed by the fix. Suggested-by:
-
- Jan 28, 2021
-
-
Michal Wajdeczko authored
While DOC: section titles are not converted into RST headings sections and are only decorated with strong emphasis markup, nothing stops us from generating internal hyperlinks for them, to mimic implicit hyperlinks to RST headings. Signed-off-by:
Michal Wajdeczko <michal.wajdeczko@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Chris Wilson <chris@chris-wilson.co.uk> Link: https://lore.kernel.org/r/20210118110813.1490-1-michal.wajdeczko@intel.com Signed-off-by:
-
- Jan 18, 2021
-
-
Mauro Carvalho Chehab authored
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 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. Signed-off-by:
-
- Dec 03, 2020
-
-
Mauro Carvalho Chehab authored
Changeset 6b80975c ("scripts: kernel-doc: fix typedef parsing") added support for things like: typedef unsigned long foo(); However, it caused a regression on this prototype: typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle); This is only noticed after adding a patch that checks if the kernel-doc identifier matches the typedef: ./scripts/kernel-doc -none $(git grep '^.. kernel-doc::' Documentation/ |cut -d ' ' -f 3|sort|uniq) 2>&1|grep expecting include/media/v4l2-dv-timings.h:38: warning: expecting prototype for typedef v4l2_check_dv_timings_fnc. Prototype was for typedef nc instead The problem is that, with the new parsing logic, it is not checking for complete words at the type part. Fix it by adding a \b at the end of each type word at the regex. fixes: 6b80975c ("scripts: kernel-doc: fix typedef parsing") Signed-off-by:
-
