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

scripts/kernel-doc: warn on excess enum value descriptions

2017-09-26T21:02:54+00:00

The existing message "Excess struct/union/enum/typedef member [...]" made it sound like this would already be done, but the code is never invoked for enums or typedefs (and really can't be). Add some code to the enum dumper to handle this there instead. While at it, also make the above message more accurate by simply dumping the type that was passed in, and pass the struct/union differentiation in. Signed-off-by: Johannes Berg Signed-off-by: Jonathan Corbet

kernel-doc parser mishandles declarations split into lines

2017-08-30T22:18:16+00:00

Reported by Johannes Berg [1]. Problem here: function process_proto_type() concatenates the striped lines of declaration without any whitespace. A one-liner of:: struct something { struct foo bar; }; has to be:: struct something {struct foo bar;}; Without the patching process_proto_type(), the result missed the space between 'foo' and 'bar':: struct something {struct foobar;}; Bugfix of process_proto_type() brings next error when blank lines between enum declaration:: warning: Enum value ' ' not described in enum 'foo' Problem here: dump_enum() does not strip leading whitespaces from the concatenated string (with the new additional space from process_proto_type). [1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg12410.html Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet

Merge tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild

2017-07-07T22:09:09+00:00

Pull misc Kbuild updates from Masahiro Yamada: - Use more portable shebang for Perl scripts - Remove trailing spaces from GCC version in kernel log - Make initramfs generation deterministic * tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: kbuild: create deterministic initramfs directory listings scripts/mkcompile_h: Remove trailing spaces from compiler version scripts: Switch to more portable Perl shebang

scripts/kernel-doc: handle DECLARE_HASHTABLE

2017-07-03T12:57:09+00:00

DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP because otherwise kernel-doc assumes the member name is the second, not first macro parameter. Signed-off-by: Jakub Kicinski Signed-off-by: Jonathan Corbet

scripts: Switch to more portable Perl shebang

2017-05-14T02:20:44+00:00

The default NetBSD package manager is pkgsrc and it installs Perl along other third party programs under custom and configurable prefix. The default prefix for binary prebuilt packages is /usr/pkg, and the Perl executable lands in /usr/pkg/bin/perl. This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's the most portable solution that should work for almost everybody. Perl's executable is detected automatically. This change switches -w option passed to the executable with more modern "use warnings;" approach. There is no functional change to the default behavior. While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?). Signed-off-by: Kamil Rytarowski Signed-off-by: Masahiro Yamada

scripts/kernel-doc: fix handling of parameters with parenthesis

2017-04-02T20:06:56+00:00

lib/crc32c defines one parameter as: const u32 (*tab)[256] Better handle parenthesis, to avoid those warnings: ./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]' ./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic' ./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]' ./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic' Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts/kernel-doc: fix parser for apostrophes

2017-04-02T20:06:50+00:00

On ReST, adding a text like ``literal`` is valid. However, the kernel-doc script won't handle it fine. We really need this feature, in order to escape things like %ph, with is found on some C files. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

kernel-doc: Handle returning pointers to pointers

2017-01-26T22:20:10+00:00

Clearly nobody ever tried to build the documentation for the radix tree before: include/linux/radix-tree.h:400: warning: cannot understand function prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter, unsigned long start) ' Indeed, the regexes only handled a single '*', not one-or-more. I have tried to fix that, but now I have perl regexes all over my hands, and I fear I shall never be clean again. Signed-off-by: Matthew Wilcox Signed-off-by: Jonathan Corbet

kernel-doc: properly document array arguments of function

2017-01-13T17:53:24+00:00

Documentation for array parameters passed in a function, like the first argument in the function below, weren't getting exported in the rst format, although they work fine for html and pdf formats: void drm_clflush_pages(struct page * pages[], unsigned long num_pages) That's because the string key to store the description in the parameterdescs dictionary doesn't have the [] suffix. This cleans up the suffix from the key before accessing the dictionary. Signed-off-by: Gabriel Krisman Bertazi Fixes: c0d1b6ee780a ("kernel-doc: produce RestructuredText output") Reviewed-by: Jani Nikula Signed-off-by: Jonathan Corbet

kernel-doc: make highlights more homogenous for the various backends

2017-01-04T22:08:14+00:00

$type_struct_full and friends are only used by the restructuredText backend, because it needs to separate enum/struct/typedef/union from the name of the type. However, $type_struct is *also* used by the rST backend. This is confusing. This patch replaces $type_struct's use in the rST backend with a new $type_fallback; it modifies $type_struct so that it can be used in the rST backend; and creates regular expressions like $type_struct for enum/typedef/union, for use in all backends. Note that, compared to $type_*_full, in the new regexes $1 includes both the "kind" and the name (before, $1 was pretty much a constant). Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet