lwn.git/scripts/kernel-doc, branch doc/4.4

scripts/kernel-doc: Replacing highlights hash by an array

2015-09-13T20:38:51+00:00

The "highlight" code is very sensible to the order of the hash keys, but the order of the keys cannot be predicted. It generates faulty DocBook entries like: - @device_for_each_child Sorting the result is not enough some times (as it's deterministic but we can't control it). We should use an array for that job, so we can guarantee that the order of the regex execution on dohighlight is correct. [jc: I think this is kind of papering around the real problem, that people are saying @function() when "function" is not a parameter. But this makes things better than they were before, so...] Signed-off-by: Danilo Cesar Lemes de Paula Signed-off-by: Jonathan Corbet

Documentation: Avoid creating man pages in source tree

2015-09-13T20:38:50+00:00

Currently kernel-doc generates a dummy DocBook file when asked to convert a C source file with no structured comments. For an out-of-tree build (objtree != srctree), the title of the output file is the absolute path name of the C source file, which later results in a manual page being created alongside the C source file. Change the title to be a relative path. Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet

scripts/kernel-doc: Processing -nofunc for functions only

2015-09-13T20:38:50+00:00

Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to avoid duplicated documentation in the next call. It works for most of the cases, but there are some specific situations where a struct has the same name of an already-exported function. Current kernel-doc behavior ignores those structs and does not add them to the final documentation. This patch fixes it. This is unusual, the only case I've found is the drm_modeset_lock (function and struct) defined in drm_modeset_lock.h and drm_modeset_lock.c. Considering this, it should only affect the DRM documentation by including struct drm_modeset_lock to the final Docbook. Signed-off-by: Danilo Cesar Lemes de Paula Signed-off-by: Jonathan Corbet

kerneldoc: Convert error messages to GNU error message format

2015-09-04T23:54:41+00:00

Editors like emacs and vi recognize a number of error message formats. The format used by the kerneldoc tool is not recognized by emacs. Change the kerneldoc error message format to the GNU style such that the emacs prev-error and next-error commands can be used to navigate through kerneldoc error messages. For more information about the GNU error message format, see also https://www.gnu.org/prep/standards/html_node/Errors.html. This patch has been generated via the following sed command: sed -i.orig 's/Error(\${file}:\$.):/\${file}:\$.: error:/g;s/Warning(\${file}:\$.):/\${file}:\$.: warning:/g;s/Warning(\${file}):/\${file}:1: warning:/g;s/Info(\${file}:\$.):/\${file}:\$.: info:/g' scripts/kernel-doc Signed-off-by: Bart Van Assche Cc: Johannes Berg Acked-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds

kernel-doc: ignore unneeded attribute information

2015-08-23T19:54:33+00:00

The kernel-doc script gets confused by __attribute__(()) strings in structures, so just clean the out. Also ignore the CRYPTO_MINALIGN_ATTR macro used in the crypto subsystem. Signed-off-by: Jonathan Corbet

scripts/kernel-doc Allow struct arguments documentation in struct body

2015-08-06T19:05:35+00:00

Describing arguments at top of a struct definition works fine for small/medium size structs, but it definitely doesn't work well for struct with a huge list of elements. Keeping the arguments list inside the struct body makes it easier to maintain the documentation. ie: /** * struct my_struct - short description * @a: first member * @b: second member * * Longer description */ struct my_struct { int a; int b; /** * @c: This is longer description of C * * You can use paragraphs to describe arguments * using this method. */ int c; }; This patch allows the use of this kind of syntax. Only one argument per comment and user can use how many paragraphs he needs. It should start with /**, which is already being used by kernel-doc. If those comment doesn't follow those rules, it will be ignored. Signed-off-by: Danilo Cesar Lemes de Paula Cc: Randy Dunlap Cc: Daniel Vetter Cc: Laurent Pinchart Cc: Jonathan Corbet Cc: Herbert Xu Cc: Stephan Mueller Cc: Michal Marek Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx Cc: dri-devel Signed-off-by: Jonathan Corbet

scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date

2015-07-10T17:03:25+00:00

Together with the preceding changes, this allows man pages to be built reproducibly. Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet

scripts/kernel-doc: parse kernel-doc deterministically

2015-07-10T17:03:05+00:00

Regular expressions for highlights in kernel-doc are stored in a Perl hash. These hashes are ordered differently for each Perl run. This will prevent kernel-doc to behave deterministically when parsing “@foo()” as in some runs it will be interpreted as a parameter and in the others it will be interpreted as a function. We now sort the %highlights hash to get the same behavior on every run. Signed-off-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet

scripts/kernel-doc: don't eat struct members with __aligned

2014-12-11T01:41:02+00:00

The change from \d+ to .+ inside __aligned() means that the following structure: struct test { u8 a __aligned(2); u8 b __aligned(2); }; essentially gets modified to struct test { u8 a; }; for purposes of kernel-doc, thus dropping a struct member, which in turns causes warnings and invalid kernel-doc generation. Fix this by replacing the catch-all (".") with anything that's not a semicolon ("[^;]"). Fixes: 9dc30918b23f ("scripts/kernel-doc: handle struct member __aligned without numbers") Signed-off-by: Johannes Berg Cc: Nishanth Menon Cc: Randy Dunlap Cc: Michal Marek Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds

scripts/kernel-doc: recognize __meminit

2014-08-26T20:49:57+00:00

Fix scripts/kernel-doc to recognize __meminit in a function prototype and to strip it, as done with many other attributes. Fixes this warning: Warning(..//mm/page_alloc.c:2973): cannot understand function prototype: 'void * __meminit alloc_pages_exact_nid(int nid, size_t size, gfp_t gfp_mask) ' Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds