#
0ec69b3b |
|
26-Mar-2024 |
Donald Hunter <donald.hunter@gmail.com> |
docs: Fix bitfield handling in kernel-doc kernel-doc doesn't handle bitfields that are specified with symbolic name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX This results in the following warnings when running `make htmldocs`: include/linux/spi/spi.h:246: warning: Function parameter or struct member 'cs_index_mask:SPI_CS_CNT_MAX' not described in 'spi_device' include/linux/spi/spi.h:246: warning: Excess struct member 'cs_index_mask' description in 'spi_device' Update the regexp for bitfields to accept all word chars, not just digits. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240326173825.99190-1-donald.hunter@gmail.com
|
#
69fc23ef |
|
26-Feb-2024 |
Akira Yokosawa <akiyks@gmail.com> |
kernel-doc: Add unary operator * to $type_param_ref In kernel-doc comments, unary operator * collides with Sphinx/ docutil's markdown for emphasizing. This resulted in additional warnings from "make htmldocs": WARNING: Inline emphasis start-string without end-string. , as reported recently [1]. Those have been worked around either by escaping * (like \*param) or by using inline-literal form of ``*param``, both of which are specific to Sphinx/docutils. Such workarounds are against the kenrel-doc's ideal and should better be avoided. Instead, add "*" to the list of unary operators kernel-doc recognizes and make the form of *@param available in kernel-doc comments. Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Link: [1] https://lore.kernel.org/r/20240223153636.41358be5@canb.auug.org.au/ Acked-by: Christoph Hellwig <hch@lst.de> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Chandan Babu R <chandanbabu@kernel.org>
|
#
8e93cb78 |
|
14-Feb-2024 |
Johannes Berg <johannes.berg@intel.com> |
kernel-doc: handle #if in enums as well In addition to #ifdef, #define and #endif, also handle any #if since we may be using e.g. #if IS_ENABLED(...). I didn't find any instances of this in the kernel now, there are enums with such ifs inside, but I didn't find any with kernel-doc as well. However, it came up as we were adding such a construct in our driver and warnings from kernel-doc were the result. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240214142937.80ee86a3beae.Ibcc5bd97a20cd10a792663e4b254cd46c7e8b520@changeid
|
#
9f6f4c11 |
|
15-Feb-2024 |
Vegard Nossum <vegard.nossum@oracle.com> |
scripts/kernel-doc: simplify signature printing Untangle some of the $is_macro logic and the nested conditionals. This makes it easier to see where and how the signature is actually printed. No functional change. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215134828.1277109-5-vegard.nossum@oracle.com
|
#
d3c55a71 |
|
15-Feb-2024 |
Vegard Nossum <vegard.nossum@oracle.com> |
scripts/kernel-doc: separate out function signature Format the entire function signature and place it in a separate variable; this both makes it easier to understand what these lines of code are doing and will allow us to simplify the code further in the following patch. No functional change. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215134828.1277109-4-vegard.nossum@oracle.com
|
#
e8ebb853 |
|
15-Feb-2024 |
Vegard Nossum <vegard.nossum@oracle.com> |
scripts/kernel-doc: simplify function printing Get rid of the $start variable, since it's really not necessary. No functional change. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215134828.1277109-3-vegard.nossum@oracle.com
|
#
a3a23d36 |
|
15-Feb-2024 |
Vegard Nossum <vegard.nossum@oracle.com> |
scripts/kernel-doc: add modeline for vim users Set 'softtabstop' to 4 spaces, which will hopefully help keep the indentation in this file consistent going forwards. This mirrors the modeline in scripts such as recordmcount.pl, ktest.pl, and others. Emacs seems to use 4 spaces to indent by default, so it doesn't require anything special here. No functional change. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215134828.1277109-2-vegard.nossum@oracle.com
|
#
af404fb1 |
|
08-Feb-2024 |
Vegard Nossum <vegard.nossum@oracle.com> |
scripts/kernel-doc: reindent This file is using an ungodly mixture of 4 spaces, 2-wide tabs, 4-wide tabs, _and_ 8-wide tabs, making it really hard to find good editor settings for working with this file. Bite the bullet and reindent it by hand. I tried using both perltidy and vim, but neither of them were up to the task without changing too much or getting confused about what they were supposed to be doing. I did change a few instances of } else into } else (and same for elsif); the file is again written using both styles, and I left functions which already seemed self-consistent alone. You can verify that this commit only changes whitespace using e.g.: git diff --ignore-all-space --word-diff or to see (only) the instances where newlines were added/removed: git diff --ignore-all-space You can also see the delta from what perltidy would have wanted to do to this file (when asked to only indent it), which isn't that much in the end: perltidy -io -fnl scripts/kernel-doc git diff --no-index scripts/kernel-doc{,.tdy} Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240208161705.888385-1-vegard.nossum@oracle.com
|
#
bbf00be9 |
|
31-Jan-2024 |
Sakari Ailus <sakari.ailus@linux.intel.com> |
kernel-doc: Support arrays of pointers struct fields In a rather unusual arrangement in include/media/v4l2-vp9.h struct v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a pointer to an array, which is what's usually done. Add support for such arrays of pointers to kernel-doc. Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Ricardo Ribalda <ribalda@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240131084934.191226-1-sakari.ailus@linux.intel.com
|
#
d2a70e28 |
|
07-Jan-2024 |
Randy Dunlap <rdunlap@infradead.org> |
kernel-doc: drop looking for "MACDOC" Linux kernel does not use "MACDOC" in any documenation or any source files, so stop searching for it. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240108003700.13418-1-rdunlap@infradead.org
|
#
e5a52766 |
|
22-Jan-2024 |
Anna-Maria Behnsen <anna-maria@linutronix.de> |
scripts/kernel-doc: Do not process backslash lines in comments To prevent this, do the pre-processing only for lines which are no comments, e.g. do not start with ' *'. Suggested-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240122093152.22536-3-anna-maria@linutronix.de
|
#
afa751e8 |
|
25-Dec-2023 |
Randy Dunlap <rdunlap@infradead.org> |
kernel-doc: handle a void function without producing a warning Currently a void function can produce a warning: main.c:469: warning: contents before sections This one is from arch/x86/kernel/cpu/sgx/main.c (which is not included in any produced kernel documentation output). Handle this by setting $in_doc_sect to 1 whenever any recognized document section name is processed. Fixes: f624adef3d0b ("kernel-doc: limit the "section header:" detection to a select few") Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231226065219.319-1-rdunlap@infradead.org
|
#
dcd39fa2 |
|
15-Dec-2023 |
Andy Shevchenko <andriy.shevchenko@linux.intel.com> |
kernel-doc: Align quick help and the code The update to the quick help mentions -Wshort-description, but code never supported for that. Align that with the code by allowing both: -Wshort-description and -Wshort-desc. Fixes: 56b0f453db74 ("kernel-doc: don't let V=1 change outcome") Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231215150341.1996720-1-andriy.shevchenko@linux.intel.com
|
#
f600c77a |
|
18-Dec-2023 |
Jonathan Corbet <corbet@lwn.net> |
docs: ignore __counted_by attribute in structure definitions kernel-doc appeared to ignore __counted_by, but appearances can be deceiving; it caused member names to not be recognized, which manifested as a number of spurious "Excess struct member" warnings. Filter that attribute out and reduce the warning onslaught slightly. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0c3ebff5 |
|
14-Dec-2023 |
Kees Cook <keescook@chromium.org> |
scripts: kernel-doc: Clarify missing struct member description The output "or member" should be more specific, instead saying "struct member". Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231215001513.work.563-kees@kernel.org
|
#
b77fdd6a |
|
14-Dec-2023 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: restore warning for Excess struct/union The warning for Excess struct or union member description was removed when the $nested parameter of check_sections() was removed. This causes some kernel-doc notation warnings to be missed. Recently the kernel test robot somehow reported an Excess member. The code in kernel-doc has not issued that warning since kernel v4.16, so I don't know how the robot did it. (See the Link for the report.) drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs' I patched that warning away even though I could not reproduce the warning from kernel-doc. The warning should be issued for extraneous struct member or union member description, so restore it. Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter") Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/ Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Reviewed-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231214070200.24405-1-rdunlap@infradead.org
|
#
aeb9ce05 |
|
29-Nov-2023 |
Coco Li <lixiaoyan@google.com> |
cache: enforce cache groups Set up build time warnings to safeguard against future header changes of organized structs. Warning includes: 1) whether all variables are still in the same cache group 2) whether all the cache groups have the sum of the members size (in the maximum condition, including all members defined in configs) The __cache_group* variables are ignored in kernel-doc check in the various header files they appear in to enforce the cache groups. Suggested-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: Coco Li <lixiaoyan@google.com> Reviewed-by: Eric Dumazet <edumazet@google.com> Reviewed-by: Shakeel Butt <shakeelb@google.com> Signed-off-by: David S. Miller <davem@davemloft.net>
|
#
cf63348b |
|
30-Oct-2023 |
Yujie Liu <yujie.liu@intel.com> |
scripts/kernel-doc: Fix the regex for matching -Werror flag Swarup reported a "make htmldocs" warning: Variable length lookbehind is experimental in regex; marked by <-- HERE in m/(?<=^|\s)-Werror(?=$|\s) <-- HERE / at ./scripts/kernel-doc line 188. Akira managed to reproduce it by perl v5.34.0. On second thought, it is not necessary to have the complicated "lookahead and lookbehind" things, and the regex can be simplified. Generally, the kernel-doc warnings should be considered as errors only when "-Werror" flag is set in KCFLAGS, but not when "-Werror=<diagnostic-type>" is set, which means there needs to be a space or start of string before "-Werror", and a space or end of string after "-Werror". The following cases have been tested to work as expected: * kernel-doc warnings are considered as errors: $ KCFLAGS="-Werror" make W=1 $ KCFLAGS="-Wcomment -Werror" make W=1 $ KCFLAGS="-Werror -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror -Wundef" make W=1 * kernel-doc warnings remain as warnings: $ KCFLAGS="-Werror=return-type" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type" make W=1 $ KCFLAGS="-Werror=return-type -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 The "Variable length lookbehind is experimental in regex" warning is also resolved by this patch. Fixes: 91f950e8b9d8 ("scripts/kernel-doc: match -Werror flag strictly") Reported-by: Swarup Laxman Kotiaklapudi <swarupkotikalapudi@gmail.com> Signed-off-by: Yujie Liu <yujie.liu@intel.com> Closes: https://lore.kernel.org/r/20231028182231.123996-1-swarupkotikalapudi@gmail.com/ Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231030085404.3343403-1-yujie.liu@intel.com
|
#
91f950e8 |
|
19-Oct-2023 |
Yujie Liu <yujie.liu@intel.com> |
scripts/kernel-doc: match -Werror flag strictly In our CI testing, we use some commands as below to only turn a specific type of warnings into errors, but we notice that kernel-doc warnings are also turned into errors unexpectedly. $ make KCFLAGS="-Werror=return-type" W=1 kernel/fork.o kernel/fork.c:1406: warning: Function parameter or member 'mm' not described in 'set_mm_exe_file' kernel/fork.c:1406: warning: Function parameter or member 'new_exe_file' not described in 'set_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'mm' not described in 'replace_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'new_exe_file' not described in 'replace_mm_exe_file' kernel/fork.c:1491: warning: Function parameter or member 'mm' not described in 'get_mm_exe_file' kernel/fork.c:1510: warning: Function parameter or member 'task' not described in 'get_task_exe_file' kernel/fork.c:1534: warning: Function parameter or member 'task' not described in 'get_task_mm' kernel/fork.c:2109: warning: bad line: kernel/fork.c:2130: warning: Function parameter or member 'ret' not described in '__pidfd_prepare' kernel/fork.c:2130: warning: Excess function parameter 'pidfd' description in '__pidfd_prepare' kernel/fork.c:2179: warning: Function parameter or member 'ret' not described in 'pidfd_prepare' kernel/fork.c:2179: warning: Excess function parameter 'pidfd' description in 'pidfd_prepare' kernel/fork.c:3195: warning: expecting prototype for clone3(). Prototype was for sys_clone3() instead 13 warnings as Errors make[3]: *** [scripts/Makefile.build:243: kernel/fork.o] Error 13 make[3]: *** Deleting file 'kernel/fork.o' make[2]: *** [scripts/Makefile.build:480: kernel] Error 2 make[1]: *** [/root/linux/Makefile:1913: .] Error 2 make: *** [Makefile:234: __sub-make] Error 2 >From the git history, commit 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") introduces a new command-line option to make kernel-doc warnings into errors. It can also read the KCFLAGS environment variable to decide whether to turn this option on, but the regex used for matching may not be accurate enough. It can match both "-Werror" and "-Werror=<diagnostic-type>", so the option is turned on by mistake in the latter case. Fix this by strictly matching the flag "-Werror": there must be a space or start of string in the front, and a space or end of string at the end. This can handle all the following cases correctly: KCFLAGS="-Werror" make W=1 [MATCH] KCFLAGS="-Werror=return-type" make W=1 [NO MATCH] KCFLAGS="-Wcomment -Werror -Wundef" make W=1 [MATCH] KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 [NO MATCH] Fixes: 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") Signed-off-by: Yujie Liu <yujie.liu@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20231019095637.2471840-1-yujie.liu@intel.com>
|
#
0ef5de7b |
|
15-Aug-2023 |
Pavan Kumar Linga <pavan.kumar.linga@intel.com> |
scripts: kernel-doc: fix macro handling in enums drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to initialize the enum enumerators: enum idpf_cap_field { IDPF_BASE_CAPS = -1, IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities, csum_caps), IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities, seg_caps), IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities, rss_caps), IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities, hsplit_caps), IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities, rsc_caps), IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities, other_caps), }; kernel-doc parses the above enumerator with a ',' inside the macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators resulting in the warnings: drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'csum_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'seg_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rss_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'hsplit_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rsc_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'other_caps' not described in enum 'idpf_cap_field' Fix it by removing the macro arguments within the parentheses. Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230815210417.98749-3-pavan.kumar.linga@intel.com
|
#
be98edcb |
|
15-Aug-2023 |
Pavan Kumar Linga <pavan.kumar.linga@intel.com> |
scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN] At present, if the macros DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN() are used in the structures as shown below, instead of parsing the parameter in the parentheses, kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and 'DEFINE_DMA_UNMAP_LEN(' which results in the following warnings: drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in 'idpf_tx_buf' drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in 'idpf_tx_buf' struct idpf_tx_buf { DEFINE_DMA_UNMAP_ADDR(dma); DEFINE_DMA_UNMAP_LEN(len); }; Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN(). Cc: Jonathan Corbet <corbet@lwn.net> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230815210417.98749-2-pavan.kumar.linga@intel.com
|
#
e27cb89a |
|
21-Jun-2023 |
Jakub Kicinski <kuba@kernel.org> |
scripts: kernel-doc: support private / public marking for enums 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: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20230621223525.2722703-1-kuba@kernel.org>
|
#
56b0f453 |
|
09-Jun-2023 |
Johannes Berg <johannes.berg@intel.com> |
kernel-doc: don't let V=1 change outcome 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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
|
#
8aaf297a |
|
05-Jun-2023 |
Mark Rutland <mark.rutland@arm.com> |
docs: scripts: kernel-doc: accept bitwise negation like ~@var 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: ee2aa7590398 ("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
|
#
c0d3b831 |
|
22-Dec-2022 |
Masahiro Yamada <masahiroy@kernel.org> |
kbuild: do not print extra logs for V=2 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: Masahiro Yamada <masahiroy@kernel.org> Reviewed-by: Nicolas Schier <nicolas@fjasle.eu>
|
#
3bdd9f07 |
|
29-Jan-2023 |
Jonathan Neuschäfer <j.neuschaefer@gmx.net> |
scripts: kernel-doc: Remove workaround for @param... syntax Commit 43756e347f21 ("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: Jonathan Corbet <corbet@lwn.net>
|
#
632ce137 |
|
29-Nov-2022 |
Jason Gunthorpe <jgg@ziepe.ca> |
scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export 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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
|
#
03699f27 |
|
02-Sep-2022 |
Kees Cook <keescook@chromium.org> |
string: Rewrite and add more kern-doc for the str*() functions 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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/lkml/9b0cf584-01b3-3013-b800-1ef59fe82476@gmail.com Signed-off-by: Kees Cook <keescook@chromium.org>
|
#
eaf710ce |
|
30-Sep-2022 |
Jonathan Corbet <corbet@lwn.net> |
docs: improve the HTML formatting of kerneldoc comments 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: Jonathan Corbet <corbet@lwn.net>
|
#
df4bf98e |
|
13-Jun-2022 |
Niklas Söderlund <niklas.soderlund@corigine.com> |
scripts: kernel-doc: Always increment warnings counter 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: Jonathan Corbet <corbet@lwn.net>
|
#
b79dfef0 |
|
26-Mar-2022 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts/kernel-doc: change the line number meta info 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: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
e334f873 |
|
24-Feb-2022 |
Akira Yokosawa <akiyks@gmail.com> |
docs: scripts/kernel-doc: Detect absence of FILE arg 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: Akira Yokosawa <akiyks@gmail.com> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/7b136049-a3ba-0eb5-8717-364d773ff914@gmail.com [jc: reworked to fix conflict with pod patches] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
2b306eca |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Refresh the copyright lines 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: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-12-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
258092a8 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Drop obsolete comments 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: Jonathan Corbet <corbet@lwn.net> Suggested-by: Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-11-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
252b47da |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Replace the usage function 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-10-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
834cf6b9 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-9-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c15de5a1 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-8-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
9c77f108 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-7-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
dd803b04 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-6-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
2875f787 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-5-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
f1583922 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Translate the DESCRIPTION section 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-4-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
43caf1a6 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Relink argument parsing error handling to pod2usage 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 <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-3-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
a5cdaea5 |
|
18-Feb-2022 |
Tomasz Warniełło <tomasz.warniello@gmail.com> |
scripts: kernel-doc: Add the basic POD sections 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: Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Disliked-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220218181628.1411551-2-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
603bdf5d |
|
29-Oct-2021 |
Randy Dunlap <rdunlap@infradead.org> |
kernel-doc: support DECLARE_PHY_INTERFACE_MASK() 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 38c310eb46f5 ("net: phylink: add MAC phy_interface_t bitmap") Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Reported-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: Jonathan Corbet <corbet@lwn.net>
|
#
a40a8a11 |
|
11-Oct-2021 |
Kees Cook <keescook@chromium.org> |
scripts: kernel-doc: Ignore __alloc_size() attribute 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: Stephen Rothwell <sfr@canb.auug.org.au> Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20211011180650.3603988-1-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
3080ea55 |
|
09-Aug-2021 |
Kees Cook <keescook@chromium.org> |
stddef: Introduce DECLARE_FLEX_ARRAY() helper 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: Kees Cook <keescook@chromium.org>
|
#
50d7bd38 |
|
17-May-2021 |
Kees Cook <keescook@chromium.org> |
stddef: Introduce struct_group() helper macro 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: Keith Packard <keithp@keithp.com> Acked-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: Dan Williams <dan.j.williams@intel.com> Signed-off-by: Kees Cook <keescook@chromium.org>
|
#
bed4ed30 |
|
30-Jul-2021 |
Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> |
scripts/kernel-doc: Override -Werror from KCFLAGS with KDOC_WERROR Since commit 2c12c8103d8f ("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: Jonathan Corbet <corbet@lwn.net>
|
#
e86bdb24 |
|
14-May-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: reduce repeated regex expressions into variables 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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210514144244.25341-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
80342d48 |
|
26-Apr-2021 |
Matthew Wilcox <willy@infradead.org> |
kernel-doc: Add support for __deprecated 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: Matthew Wilcox (Oracle) <willy@infradead.org> Link: https://lore.kernel.org/r/20210427114828.GY235567@casper.infradead.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
f9bbc12c |
|
14-Apr-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: improve parsing for kernel-doc comments syntax 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: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net Signed-off-by: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com [ jc: fixed some line-length issues ] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
3e58e839 |
|
29-Mar-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: add warning for comment not following kernel-doc syntax 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: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
212209cf |
|
26-Mar-2021 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: properly recognize parameter lines with colons 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: Stephen Rothwell <sfr@canb.auug.org.au> Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences") Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
8d295fba |
|
25-Mar-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
kernel-doc: better handle '::' sequences 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: Jonathan Corbet <corbet@lwn.net>
|
#
0b54c2e3 |
|
03-Mar-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel-doc: ignore identifier on anonymous enums 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/055ad57879f1b9381b90879e00f72fde1c3a5647.1614760910.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
084aa001 |
|
06-Mar-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: fix attribute capture in function parsing 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: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210306113510.31023-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
a746fe32 |
|
25-Feb-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: fix typedef support for struct/union parsing 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: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210225145033.11431-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
336ced2d |
|
17-Feb-2021 |
Aditya Srivastava <yashsri421@gmail.com> |
scripts: kernel-doc: fix array element capture in pointer-to-func parsing 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: Lukas Bulwahn <lukas.bulwahn@gmail.com> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com> Tested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com> Link: https://lore.kernel.org/r/20210217145625.14006-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
06a755d6 |
|
17-Jan-2021 |
Michal Wajdeczko <michal.wajdeczko@intel.com> |
scripts/kernel-doc: add internal hyperlink to DOC: sections 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: Jonathan Corbet <corbet@lwn.net>
|
#
52042e2d |
|
14-Jan-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: validate kernel-doc markup with the actual names 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/081546f141a496d6cabb99a4adc140444c705e93.1610610937.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7d2c6b1e |
|
02-Dec-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: fix parsing function-like typedefs Changeset 6b80975c6308 ("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: 6b80975c6308 ("scripts: kernel-doc: fix typedef parsing") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/218ff56dcb8e73755005d3fb64586eb1841a276b.1606896997.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
ae5b17e4 |
|
02-Nov-2020 |
Andy Shevchenko <andriy.shevchenko@linux.intel.com> |
scripts: kernel-doc: Restore anonymous enum parsing The commit d38c8cfb0571 ("scripts: kernel-doc: add support for typedef enum") broke anonymous enum parsing. Restore it by relying on members rather than its name. Fixes: d38c8cfb0571 ("scripts: kernel-doc: add support for typedef enum") Reported-by: kernel test robot <lkp@intel.com> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/20201102170637.36138-1-andriy.shevchenko@linux.intel.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
72b97d0b |
|
27-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: use :c:union when needed Sphinx C domain code after 3.2.1 will start complaning if :c:struct would be used for an union type: .../Documentation/gpu/drm-kms-helpers:352: ../drivers/video/hdmi.c:851: WARNING: C 'identifier' cross-reference uses wrong tag: reference name is 'union hdmi_infoframe' but found name is 'struct hdmi_infoframe'. Full reference name is 'union hdmi_infoframe'. Full found name is 'struct hdmi_infoframe'. So, let's address this issue too in advance, in order to avoid future issues. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/6e4ec3eec914df62389a299797a3880ae4490f35.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7efc6c42 |
|
27-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: split typedef complex regex The typedef regex for function prototypes are very complex. Split them into 3 separate regex and then join them using qr. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/3a4af999a0d62d4ab9dfae1cdefdfcad93383356.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
6b80975c |
|
27-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: fix typedef parsing The include/linux/genalloc.h file defined this typedef: typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr); Because it has a type composite of two words (unsigned long), the parser gets the typedef name wrong: .. c:macro:: long **Typedef**: Allocation callback function type definition Fix the regex in order to accept composite types when defining a typedef for a function pointer. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/328e8018041cc44f7a1684e57f8d111230761c4f.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
6e9e4158 |
|
30-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: try to use c:function if possible 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>
|
#
5ef09c96 |
|
09-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: fix line number handling 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>
|
#
93351d41 |
|
04-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: allow passing desired Sphinx C domain dialect 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>
|
#
ed8348e2 |
|
29-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: don't mangle with parameter list 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>
|
#
47bcacfd |
|
30-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: fix typedef identification 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>
|
#
eab795dd |
|
29-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: reimplement -nofunction argument 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>
|
#
dbe8ba00 |
|
27-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: fix troubles with line counts 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>
|
#
e3ad05fe |
|
25-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x 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>
|
#
efa44475 |
|
24-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: make it more compatible with Sphinx 3.x 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>
|
#
d38c8cfb |
|
01-Oct-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: add support for typedef enum 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>
|
#
a070991f |
|
10-Sep-2020 |
Jonathan Cameron <Jonathan.Cameron@huawei.com> |
kernel-doc: add support for ____cacheline_aligned attribute 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>
|
#
5eb6b4b3 |
|
09-Sep-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
kernel-doc: include line numbers for function prototypes 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>
|
#
2c12c810 |
|
28-Jul-2020 |
Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> |
scripts/kernel-doc: optionally treat warnings as errors 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>
|
#
7ae281b0 |
|
23-Jun-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel-doc: handle function pointer prototypes 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>
|
#
3556108e |
|
23-Jun-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK 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>
|
#
93431e06 |
|
26-May-2020 |
Alexander A. Klimov <grandmaster@al2klimov.de> |
Replace HTTP links with HTTPS ones: documentation 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>
|
#
0d55d48b |
|
14-Apr-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: accept blank lines on parameter description 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>
|
#
ee2aa759 |
|
14-Apr-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: accept negation like !@var 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>
|
#
346282db |
|
14-Apr-2020 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts: kernel-doc: proper handle @foo->bar() 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>
|
#
e8f4ba83 |
|
14-Apr-2020 |
Peter Maydell <peter.maydell@linaro.org> |
scripts/kernel-doc: Add missing close-paren in c:function directives 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>
|
#
43756e34 |
|
07-Nov-2019 |
Jonathan Neuschäfer <j.neuschaefer@gmx.net> |
scripts/kernel-doc: Add support for named variable macro arguments 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>
|
#
f861537d |
|
17-Sep-2019 |
André Almeida <andrealmeid@collabora.com> |
kernel-doc: add support for ____cacheline_aligned_in_smp attribute 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>
|
#
2b5f78e5 |
|
17-Sep-2019 |
André Almeida <andrealmeid@collabora.com> |
kernel-doc: fix processing nested structs with attributes 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>
|
#
15e2544e |
|
12-Aug-2019 |
Andy Shevchenko <andriy.shevchenko@linux.intel.com> |
kernel-doc: Allow anonymous enum 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>
|
#
95e760cb |
|
05-Aug-2019 |
Randy Dunlap <rdunlap@infradead.org> |
kernel-doc: ignore __printf attribute 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>
|
#
344fdb28 |
|
21-Jun-2019 |
Jonathan Corbet <corbet@lwn.net> |
kernel-doc: Don't try to mark up function names 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>
|
#
b0d60bfb |
|
24-May-2019 |
Jonathan Corbet <corbet@lwn.net> |
kernel-doc: always name missing kerneldoc sections 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>
|
#
be5cd20c |
|
11-Jan-2019 |
Jonathan Corbet <corbet@lwn.net> |
kernel-doc: suppress 'not described' warnings for embedded struct fields 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>
|
#
3d9bfb19 |
|
22-Nov-2018 |
Sakari Ailus <sakari.ailus@linux.intel.com> |
scripts/kernel-doc: Fix struct and struct field attribute processing 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>
|
#
bfd228c7 |
|
07-Nov-2018 |
Mike Rapoport <rppt@kernel.org> |
kernel-doc: extend $type_param to match members referenced by pointer 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>
|
#
76dd3e7b |
|
07-Nov-2018 |
Mike Rapoport <rppt@kernel.org> |
kernel-doc: kill trailing whitespace Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
cf419d54 |
|
17-Oct-2018 |
Randy Dunlap <rdunlap@infradead.org> |
kernel-doc: fix declaration type determination 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>
|
#
673bb2df |
|
05-Aug-2018 |
Ben Hutchings <ben@decadent.org.uk> |
scripts/kernel-doc: Escape all literal braces in regexes 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>
|
#
701b3a3c |
|
16-Jul-2018 |
Valdis Kletnieks <valdis.kletnieks@vt.edu> |
PATCH scripts/kernel-doc 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>
|
#
d404d579 |
|
29-Mar-2018 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs: kernel-doc: fix parsing of arrays 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>
|
#
0891f959 |
|
15-Mar-2018 |
Matthew Wilcox <willy@infradead.org> |
kernel-doc: Remove __sched markings 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>
|
#
38476378 |
|
20-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: Add an SPDX header to kernel-doc 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>
|
#
fe7bc493 |
|
16-Feb-2018 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: support in-line comments on nested structs/unions 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>
|
#
a8dae20b |
|
13-Feb-2018 |
Mike Rapoport <rppt@linux.vnet.ibm.com> |
scripts: kernel_doc: fixup reporting of function identifiers 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>
|
#
af250290 |
|
06-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Don't mangle literal code blocks in comments 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>
|
#
c17add56 |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Finish moving STATE_* code out of process_file() 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>
|
#
cc794812 |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Move STATE_PROTO processing into its own function 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>
|
#
d742f24d |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Move STATE_BODY processing to a separate function 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>
|
#
3cac2bc4 |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Move STATE_NAME processing into its own function 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>
|
#
07048d13 |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Move STATE_NORMAL processing into its own function 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>
|
#
17b78717 |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Rename and split STATE_FIELD 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>
|
#
0bba924c |
|
05-Feb-2018 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Get rid of xml_escape() and friends 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>
|
#
85afe608 |
|
30-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel_doc: better handle show warnings logic 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>
|
#
2defb272 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: apply filtering rules to warnings 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>
|
#
84ce5b98 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: improve nested logic to handle multiple identifiers It is possible to use nested structs like: struct { struct { void *arg1; } st1, st2, *st3, st4; }; Handling it requires to split each parameter. Change the logic to allow such definitions. In order to test the new nested logic, the following file was used to test <code> struct foo { int a; }; /* Just to avoid errors if compiled */ /** * struct my_struct - a struct with nested unions and structs * @arg1: first argument of anonymous union/anonymous struct * @arg2: second argument of anonymous union/anonymous struct * @arg1b: first argument of anonymous union/anonymous struct * @arg2b: second argument of anonymous union/anonymous struct * @arg3: third argument of anonymous union/anonymous struct * @arg4: fourth argument of anonymous union/anonymous struct * @bar.st1.arg1: first argument of struct st1 on union bar * @bar.st1.arg2: second argument of struct st1 on union bar * @bar.st1.bar1: bar1 at st1 * @bar.st1.bar2: bar2 at st1 * @bar.st2.arg1: first argument of struct st2 on union bar * @bar.st2.arg2: second argument of struct st2 on union bar * @bar.st3.arg2: second argument of struct st3 on union bar * @f1: nested function on anonimous union/struct * @bar.st2.f2: nested function on named union/struct */ struct my_struct { /* Anonymous union/struct*/ union { struct { char arg1 : 1; char arg2 : 3; }; struct { int arg1b; int arg2b; }; struct { void *arg3; int arg4; int (*f1)(char foo, int bar); }; }; union { struct { int arg1; int arg2; struct foo bar1, *bar2; } st1; /* bar.st1 is undocumented, cause a warning */ struct { void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */ int arg2; int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */ } st2, st3, *st4; int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */ } bar; /* bar is undocumented, cause a warning */ /* private: */ int undoc_privat; /* is undocumented but private, no warning */ /* public: */ int undoc_public; /* is undocumented, cause a warning */ }; </code> It produces the following warnings, as expected: test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct' Suggested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7c0d7e87 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: handle nested struct function arguments Function arguments are different than usual ones. So, an special logic is needed in order to handle such arguments on nested structs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
151c468b |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: print the declaration name on warnings The logic at create_parameterlist()'s ancillary push_parameter() function has already a way to output the declaration name, with would help to discover what declaration is missing. However, currently, the logic is utterly broken, as it uses the var $type with a wrong meaning. With the current code, it will never print anything. I suspect that originally it was using the second argument of output_declaration(). I opted to not rely on a globally defined $declaration_name, but, instead, to pass it explicitly as a parameter. While here, I removed a unaligned check for !$anon_struct_union. This is not needed, as, if $anon_struct_union is not zero, $parameterdescs{$param} will be defined. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
1081de2d |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: get rid of $nested parameter The check_sections() function has a $nested parameter, meant to identify when a nested struct is present. As we now have a logic that handles it, get rid of such parameter. Suggested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
8ad72163 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: parse next structs/unions There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7c9aa015 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: replace tabs by spaces Sphinx has a hard time dealing with tabs, causing it to misinterpret paragraph continuation. As we're now mainly focused on supporting ReST output, replace tabs by spaces, in order to avoid troubles when the output is parsed by Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
bdfe2be3 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: change default to ReST format Right now, if kernel-doc is called without arguments, it defaults to man pages. IMO, it makes more sense to default to ReST, as this is the output that it is most used nowadays, and it easier to check if everything got parsed fine on an enriched text mode format. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b031ac4e |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: improve argument handling Right now, if one uses "--rst" instead of "-rst", it just ignore the argument and produces a man page. Change the logic to accept both "-cmd" and "--cmd". Also, if "cmd" doesn't exist, print the usage information and exit. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b0514267 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts: kernel-doc: get rid of unused output formats Since there isn't any docbook code anymore upstream, we can get rid of several output formats: - docbook/xml, html, html5 and list formats were used by the old build system; - As ReST is text, there's not much sense on outputting on a different text format. After this patch, only man and rst output formats are supported. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
857af3b7 |
|
18-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs: get rid of kernel-doc-nano-HOWTO.txt Everything there is already described at Documentation/doc-guide/kernel-doc.rst. So, there's no reason why to keep it anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
45005b27 |
|
08-Dec-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
kernel-doc: parse DECLARE_KFIFO and DECLARE_KFIFO_PTR() On media, we now have an struct declared with: struct lirc_fh { struct list_head list; struct rc_dev *rc; int carrier_low; bool send_timeout_reports; DECLARE_KFIFO_PTR(rawir, unsigned int); DECLARE_KFIFO_PTR(scancodes, struct lirc_scancode); wait_queue_head_t wait_poll; u8 send_mode; u8 rec_mode; }; gpiolib.c has a similar declaration with DECLARE_KFIFO(). Currently, those produce the following error: ./include/media/rc-core.h:96: warning: No description found for parameter 'int' ./include/media/rc-core.h:96: warning: No description found for parameter 'lirc_scancode' ./include/media/rc-core.h:96: warning: Excess struct member 'rawir' description in 'lirc_fh' ./include/media/rc-core.h:96: warning: Excess struct member 'scancodes' description in 'lirc_fh' ../drivers/gpio/gpiolib.c:601: warning: No description found for parameter '16' ../drivers/gpio/gpiolib.c:601: warning: Excess struct member 'events' description in 'lineevent_state' So, teach kernel-doc how to parse DECLARE_KFIFO() and DECLARE_KFIFO_PTR(). While here, relax at the past DECLARE_foo() macros, accepting a random number of spaces after comma. The addition of DECLARE_KFIFO() was Suggested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
e814bccb |
|
29-Nov-2017 |
Will Deacon <will@kernel.org> |
scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none My bisect scripts starting running into build failures when trying to compile 4.15-rc1 with the builds failing with things like: drivers/net/wireless/broadcom/brcm80211/brcmfmac/sdio.c:2078: error: Cannot parse struct or union! The line in question is actually just a #define, but after some digging it turns out that my scripts pass W=1 and since commit 3a025e1d1c2ea ("Add optional check for bad kernel-doc comments") that results in kernel-doc running on each source file. The file in question has a badly formatted comment immediately before the #define: /** * struct brcmf_skbuff_cb reserves first two bytes in sk_buff::cb for * bus layer usage. */ which causes the regex in dump_struct to fail (lack of braces following struct declaration) and kernel-doc returns 1, which causes the build to fail. Fix the issue by always returning 0 from kernel-doc when invoked with -none. It successfully generates no documentation, and prints out any issues. Cc: Matthew Wilcox <mawilcox@microsoft.com> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Will Deacon <will.deacon@arm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
3a025e1d |
|
20-Nov-2017 |
Matthew Wilcox <willy@infradead.org> |
Add optional check for bad kernel-doc comments Implement a '-none' output mode for kernel-doc which will only output warning messages, and suppresses the warning message about there being no kernel-doc in the file. If the build has requested additional warnings, automatically check all .c files. This patch does not check .h files. Enabling the warning by default would add about 1300 warnings, so it's default off for now. People who care can use this to check they didn't break the docs and maybe we'll get all the warnings fixed and be able to enable this check by default in the future. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
4675ff05 |
|
15-Nov-2017 |
Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com> |
kmemcheck: rip it out Fix up makefiles, remove references, and git rm kmemcheck. Link: http://lkml.kernel.org/r/20171007030159.22241-4-alexander.levin@verizon.com Signed-off-by: Sasha Levin <alexander.levin@verizon.com> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: Vegard Nossum <vegardno@ifi.uio.no> Cc: Pekka Enberg <penberg@kernel.org> Cc: Michal Hocko <mhocko@kernel.org> Cc: Eric W. Biederman <ebiederm@xmission.com> Cc: Alexander Potapenko <glider@google.com> Cc: Tim Hansen <devtimhansen@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
5cb5c31c |
|
19-Sep-2017 |
Johannes Berg <johannes.berg@intel.com> |
scripts/kernel-doc: warn on excess enum value descriptions 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 <johannes.berg@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
463a0fdc |
|
16-Jun-2017 |
Markus Heiser <markus.heiser@darmarit.de> |
kernel-doc parser mishandles declarations split into lines 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 <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
1cb566ba |
|
30-Jun-2017 |
Jakub Kicinski <kuba@kernel.org> |
scripts/kernel-doc: handle DECLARE_HASHTABLE 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 <jakub.kicinski@netronome.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
cb77f0d6 |
|
07-May-2017 |
Kamil Rytarowski <n54@gmx.com> |
scripts: Switch to more portable Perl shebang 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 <n54@gmx.com> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
|
#
f9b5c530 |
|
30-Mar-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts/kernel-doc: fix handling of parameters with parenthesis 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b97f193a |
|
30-Mar-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
scripts/kernel-doc: fix parser for apostrophes 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
5a0bc578 |
|
23-Jan-2017 |
Matthew Wilcox <willy@infradead.org> |
kernel-doc: Handle returning pointers to pointers 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 <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
ada5f446 |
|
09-Jan-2017 |
Gabriel Krisman Bertazi <krisman@collabora.co.uk> |
kernel-doc: properly document array arguments of function 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 <krisman@collabora.co.uk> Fixes: c0d1b6ee780a ("kernel-doc: produce RestructuredText output") Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
df31175b |
|
02-Jan-2017 |
Paolo Bonzini <pbonzini@redhat.com> |
kernel-doc: make highlights more homogenous for the various backends $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 <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
5267dd35 |
|
02-Jan-2017 |
Paolo Bonzini <pbonzini@redhat.com> |
kernel-doc: make member highlighting available in all backends Note that, in order to produce the correct Docbook markup, the "." or "->" must be separated from the member name in the regex's captured fields. For consistency, this change is applied to $type_member and $type_member_func too, not just to $type_member_xml. List mode only prints the struct name, to avoid any undesired change in the operation of docproc. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
fc6d7af8 |
|
02-Jan-2017 |
Paolo Bonzini <pbonzini@redhat.com> |
kernel-doc: include parameter type in docbook output The restructuredText output includes both the parameter type and the name for functions and function-typed members. Do the same for docbook. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b1aaa546 |
|
02-Jan-2017 |
Paolo Bonzini <pbonzini@redhat.com> |
kernel-doc: strip attributes even if they have an argument An inline function can have an attribute, as in include/linux/log2.h, and kernel-doc handles this already for simple cases. However, some attributes have arguments (e.g. the "target" attribute). Handle those too. Furthermore, attributes could be at the beginning of a function declaration, before the return type. To correctly handle this case, you need to strip spaces after the attributes; otherwise, dump_function is left confused. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
02a4f4fe |
|
02-Jan-2017 |
Paolo Bonzini <pbonzini@redhat.com> |
kernel-doc: cleanup parameter type in function-typed arguments A prototype like /** * foo - sample definition * @bar: a parameter */ int foo(int (*bar)(int x, int y)); is currently producing .. c:function:: int foo (int (*bar) (int x, int y) sample definition **Parameters** ``int (*)(int x, int y) bar`` a parameter Collapse the spaces so that the output is nicer. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0c9aa209 |
|
16-Nov-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: add support for one line inline struct member doc comments kernel-doc supports documenting struct members "inline" since a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation in struct body"). This requires the inline kernel-doc comments to have the opening and closing comment markers (/** and */ respectively) on lines of their own, even for short comments. For example: /** * struct foo - struct documentation */ struct foo { /** * @bar: member documentation */ int bar; }; Add support for one line inline comments: /** * struct foo - struct documentation */ struct foo { /** @bar: member documentation */ int bar; }; Note that mixing of the two in one doc comment is not allowed; either both comment markers must be on lines of their own, or both must be on the one line. This limitation keeps both the comments more uniform, and kernel-doc less complicated. Cc: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c950a173 |
|
28-Oct-2016 |
Silvio Fricke <silvio.fricke@gmail.com> |
kernel-doc: better parsing of named variable arguments Without this patch we get warnings for named variable arguments. warning: No description found for parameter '...' warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue' Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com> Reviewed-by: Jani Nikula <jani.nikula@intel.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
5219f18a |
|
24-Aug-2016 |
Jonathan Corbet <corbet@lwn.net> |
docs: Special-case function-pointer parameters in kernel-doc Add yet another regex to kernel-doc to trap @param() references separately and not produce corrupt RST markup. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
ef00028b |
|
26-Aug-2016 |
Jonathan Corbet <corbet@lwn.net> |
docs: make kernel-doc handle varargs properly As far as I can tell, the handling of "..." arguments has never worked right, so any documentation provided was ignored in favor of "variable arguments." This makes kernel-doc handle "@...:" as documented. It does *not* fix spots in kerneldoc comments that don't follow that convention, but they are no more broken than before. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
82801d06 |
|
30-Aug-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs-rst: kernel-doc: fix typedef output in RST format When using a typedef function like this one: typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle); The Sphinx C domain expects it to create a c:type: reference, as that's the way it creates the type references when parsing a c:function:: declaration. So, a declaration like: .. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle) Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`. So, when outputting such typedefs in RST format, we need to handle this special case, as otherwise it will produce those warnings: ./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc So, change the kernel-doc script to produce a RST output for the above typedef as: .. c:type:: v4l2_check_dv_timings_fnc **Typedef**: timings check callback **Syntax** ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);`` Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
d37c43ce |
|
30-Aug-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs-rst: improve typedef parser Improve the parser to handle typedefs like: typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle); Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
6d232c80 |
|
22-Aug-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs-rst: kernel-doc: better output struct members Right now, for a struct, kernel-doc produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting a member name in verbatim and adding a continuation line causes the LaTeX output to generate something like: item[atomic_t prios\[4\]] array with elements to store the array priorities Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name. is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` array with elements to store the array priorities Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
aa10a782 |
|
15-Aug-2016 |
Markus Heiser <markus.heiser@darmarIT.de> |
doc-rst: Revert "kernel-doc: fix handling of address_space tags" This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e. From the origin comit log:: The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it Since the kernel-doc parser does NOT make use of the cpp:domain, there is no need to change the kernel-doc parser eleminating the address_space tags. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
a3f57ad0 |
|
23-Jul-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
doc-rst: kernel-doc: fix a change introduced by mistake changeset b7e67f6c1bf7 ("doc-rst: linux_tv: supress lots of warnings") were meant to touch only on media files, but it also touched at this script by mistake. Revert such change. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
#
a88b1672 |
|
22-Jul-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
doc-rst: kernel-doc: fix handling of address_space tags The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it: Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration. If the function has no return type: Error in declarator or parameters and qualifiers Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) --------^ If the function has a return type: Error in declarator or parameters and qualifiers If pointer to member declarator: Invalid definition: Expected '::' in pointer to member (function). [error at 37] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) -------------------------------------^ If declarator-id: Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) ------------------------------------------------------------------------------------------------------^ So, we have to remove it from the function prototype. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
e7ca311e |
|
15-Jul-2016 |
Daniel Vetter <daniel.vetter@ffwll.ch> |
kernel-doc: Fix up warning output While trying to make gpu docs warning free I stumbled over one output which wasn't following proper compiler error output standards. Fix it up for more quickfix awesomeness. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
64e49546 |
|
03-Jul-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
doc-rst: linux_tv: remove trailing comments The conversion script added some comments at the end. They point to the original DocBook files, with will be removed after the manual fixes. So, they'll be pointing to nowere. So, remove those comments. They'll be forever stored at the Kernel tree. So, if someone wants the references, it is just a matter of looking at the backlog. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
#
b7e67f6c |
|
02-Jul-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
doc-rst: linux_tv: supress lots of warnings The c language parser checks if there are duplicated object definitions. That causes lots of warnings like: WARNING: duplicate C object description of ioctl Let's remove those by telling Sphinx that the language for those objects are c++. The look of the descriptions will be close, and the warnings will be gone. Please notice that we had to keep a few of them as C, as the c++ parser seems to be broken when it finds an enum. Yet, this reduced from 219 warnings to 143, with is a good thing. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
#
c9b2cfb3 |
|
07-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: unify all EXPORT_SYMBOL scanning to one place Scan all input files for EXPORT_SYMBOLs along with the explicitly specified export files before actually parsing anything. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
88c2b57d |
|
07-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs If the kernel-doc comments for functions are not in the same file as the EXPORT_SYMBOL statements, the -export and -internal output selections do not work as expected. This is typically the case when the kernel-doc comments are in header files next to the function declarations and the EXPORT_SYMBOL statements are next to the function definitions in the source files. Let the user specify additional source files in which to look for the EXPORT_SYMBOLs using the new -export-file FILE option, which may be given multiple times. The pathological example for this is include/net/mac80211.h, which has all the kernel-doc documentation for the exported functions defined in a plethora of source files net/mac80211/*.c. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
1ad560e4 |
|
07-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: abstract filename mapping Reduce duplication in follow-up work. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
da9726ec |
|
07-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: add missing semi-colons in option parsing Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
95b6be9d |
|
10-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: do not warn about duplicate default section names Since commit 32217761ee9db0215350dfe1ca4e66f312fb8c54 Author: Jani Nikula <jani.nikula@intel.com> Date: Sun May 29 09:40:44 2016 +0300 kernel-doc: concatenate contents of colliding sections we started getting (more) errors on duplicate section names, especially on the default section name "Description": include/net/mac80211.h:3174: warning: duplicate section name 'Description' This is usually caused by a slightly unorthodox placement of parameter descriptions, like in the above case, and kernel-doc resetting back to the default section more than once within a kernel-doc comment. Ignore warnings on the duplicate section name automatically assigned by kernel-doc, and only consider explicitly user assigned duplicate section names an issue. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
5668604a |
|
10-Jun-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: remove old debug cruft from dump_section() No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
8569de68 |
|
09-Jun-2016 |
Jonathan Corbet <corbet@lwn.net> |
docs: kernel-doc: Add "example" and "note" to the magic section types Lots of kerneldoc entries use "example:" or "note:" as section headers. Until such a time as we can make them use proper markup, make them work as intended. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0b0f5f29 |
|
03-Jun-2016 |
Daniel Vetter <daniel.vetter@ffwll.ch> |
scripts/kernel-doc: Add option to inject line numbers Opt-in since this wreaks the rst output and must be removed by consumers again. This is useful to adjust the linenumbers for included kernel-doc snippets in shinx. With that sphinx error message will be accurate when there's issues with the rst-ness of the kernel-doc comments. Especially when transitioning a new docbook .tmpl to .rst this is extremely useful, since you can just use your editors compilation quickfix list to accurately jump from error to error. v2: - Also make sure that we filter the LINENO for purpose/at declaration start so it only shows for selected blocks, not all of them (Jani). While at it make it a notch more accurate. - Avoid undefined $lineno issues. I tried filtering these out at the callsite, but Jani spotted more when linting the entire kernel. Unamed unions and similar things aren't stored consistently and end up with an undefined line number (but also no kernel-doc text, just the parameter type). Simplify things and filter undefined line numbers in print_lineno() to catch them all. v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines or any other special sections that directly jump to the description after the "name - purpose" line. Only really possible for functions without parameters. Noticed by Jani. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
b7afa92b |
|
01-Jun-2016 |
Daniel Vetter <daniel.vetter@ffwll.ch> |
scripts/kernel-doc: Also give functions symbolic names state3 = prototype parsing, so name them accordingly. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
ebff7f92 |
|
01-Jun-2016 |
Daniel Vetter <daniel.vetter@ffwll.ch> |
scripts/kernel-doc: Remove duplicated DOC: start handling Further up in the state machinery we switch from STATE_NAME to STATE_DOCBLOCK when we match /$doc_block/. Which means this block of code here is entirely unreachable, unless there are multiple DOC: sections within a single kernel-doc comment. Getting a list of all the files with more than one DOC: section using $ git grep -c " * DOC:" | grep -v ":1$" and then doing a full audit of them reveals there are no such comment blocks in the kernel. Supporting multiple DOC: sections in a single kernel-doc comment does not seem like a recommended way of doing things anyway, so nuke the code for simplicity. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> [Jani: amended the commit message] Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
2f4ad40a |
|
30-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: reset contents and section harder If the documentation comment does not have params or sections, the section heading may leak from the previous documentation comment. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
32217761 |
|
29-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: concatenate contents of colliding sections If there are multiple sections with the same section name, the current implementation results in several sections by the same heading, with the content duplicated from the last section to all. Even if there's the error message, a more graceful approach is to combine all the identically named sections into one, with concatenated contents. With the supported sections already limited to select few, there are massively fewer collisions than there used to be, but this is still useful for e.g. when function parameters are documented in the middle of a documentation comment, with description spread out above and below. (This is not a recommended documentation style, but used in the kernel nonetheless.) We can now also demote the error to a warning. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
f624adef |
|
29-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: limit the "section header:" detection to a select few kernel-doc currently identifies anything matching "section header:" (specifically a string of word characters and spaces followed by a colon) as a new section in the documentation comment, and renders the section header accordingly. Unfortunately, this turns all uses of colon into sections, mostly unintentionally. Considering the output, erroneously creating sections when not intended is always worse than erroneously not creating sections when intended. For example, a line with "http://example.com" turns into a "http" heading followed by "//example.com" in normal text style, which is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even if "WARNING" does not turn into a heading. It is virtually impossible to change all the kernel-doc comments, either way. The compromise is to pick the most commonly used and depended on section headers (with variants) and accept them as section headers. The accepted section headers are, case insensitive: * description: * context: * return: * returns: Additionally, case sensitive: * @return: All of the above are commonly used in the kernel-doc comments, and will result in worse output if not identified as section headers. Also, kernel-doc already has some special handling for all of them, so there's nothing particularly controversial in adding more special treatment for them. While at it, improve the whitespace handling surrounding section names. Do not consider the whitespace as part of the name. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
cddfe325 |
|
28-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: remove fixme comment Yes, for our purposes the type should contain typedef. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
d4b08e0c |
|
27-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: use *undescribed* instead of _undescribed_ The latter isn't special to rst. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
b7886de4 |
|
27-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: strip leading whitespace from continued param descs If a param description spans multiple lines, check any leading whitespace in the first continuation line, and remove same amount of whitespace from following lines. This allows indentation in the multi-line parameter descriptions for aesthetical reasons while not causing accidentally significant indentation in the rst output. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
0a726301 |
|
28-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: improve handling of whitespace on the first line param description Handle whitespace on the first line of param text as if it was the empty string. There is no need to add the newline in this case. This improves the rst output in particular, where blank lines may be problematic in parameter lists. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
ecbcfba1 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: change the output layout Move away from field lists, and simply use **strong emphasis** for section headings on lines of their own. Do not use rst section headings, because their nesting depth depends on the surrounding context, which kernel-doc has no knowledge of. Also, they do not need to end up in any table of contexts or indexes. There are two related immediate benefits. Field lists are typically rendered in two columns, while the new style uses the horizontal width better. With no extra indent on the left, there's no need to be as fussy about it. Field lists are more susceptible to indentation problems than the new style. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
6450c895 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: strip leading blank lines from inline doc comments The inline member markup allows whitespace lines before the actual documentation starts. Strip the leading blank lines. This improves the rst output. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
830066a7 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: blank lines in output are not needed Current approach leads to two blank lines, while one is enough. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
a0b96c2d |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: fix wrong code indentation No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
13901ef2 |
|
25-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: do not regard $, %, or & prefixes as special in section names The use of these is confusing in the script, and per this grep, they're not used anywhere anyway: $ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)" While at it, throw out the constants array, nothing is ever put there again. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
c099ff69 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: highlight function/struct/enum purpose lines too Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose line too. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
9c9193c4 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: drop redundant unescape in highlighting This bit is already done by xml_unescape() above. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
f3341dcf |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: add support for struct/union/enum member references Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the struct/union/enum foo definition. The members themselves do not currently have anchors to link to, but this is better than nothing, and promotes a universal notation. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
47ae7aed |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: add support for &union foo and &typedef foo references Let the user use "&union foo" and "&typedef foo" to reference foo. The difference to using "union &foo", "typedef &foo", or just "&foo" (which are valid too) is that "union" and "typedef" become part of the link text. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
a7291e7e |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: &foo references are more universal than structs It's possible to use &foo to reference structs, enums, typedefs, etc. in the Sphinx C domain. Thus do not prefix the links with "struct". Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
a19bce64 |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: reference functions according to C domain spec The Sphinx C domain spec says function references should include the parens (). Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
9e72184b |
|
29-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: do not output DOC: section titles for requested ones If the user requests a specific DOC: section by name, do not output its section title. In these cases, the surrounding context already has a heading, and the DOC: section title is only used as an identifier and a heading for clarity in the source file. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
b6c3f456 |
|
29-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: add names for output selection Make the output selection a bit more readable by adding constants for the various types of output selection. While at it, actually call the variable for choosing what to output $output_selection. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
48af606a |
|
26-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: add names for states and substates Make the state machine a bit more readable by adding constants for parser states and inline member documentation parser substates. While at it, rename the "split" documentation to "inline" documentation. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
86ae2e38 |
|
21-Jan-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: support printing exported and non-exported symbols Currently we use docproc to figure out which symbols are exported, and then docproc calls kernel-doc on specific functions, to get documentation on exported functions. According to git blame and docproc comments, this is due to historical reasons, as functions and their corresponding EXPORT_SYMBOL* may have been in different files. However for more than ten years the recommendation in CodingStyle has been to place the EXPORT_SYMBOL* immediately after the closing function brace line. Additionally, the kernel-doc comments for functions are generally placed above the function definition in the .c files (i.e. where the EXPORT_SYMBOL* is) rather than above the declaration in the .h files. There are some exceptions to this, but AFAICT none of these are included in DocBook documentation using the "!E" docproc directive. Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the function definition, kernel-doc can extract the exported vs. not information by making two passes on the input file. Add support for that via the new -export and -internal parameters. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
5e64fa9c |
|
19-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc/rst: fix use of uninitialized value I'm not quite sure why the errors below are happening, but this fixes them. Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819, <IN> line 6494. Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line 1759, <IN> line 6494. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
#
62850976 |
|
12-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: use rst C domain directives and references for types First, the headings for structs, enums and typedefs will be similar to functions. Second, this provides a kind of namespace for cross references. Third, and most importantly, the return and parameter types from .. c:function:: definitions will automagically become cross references to the documented types. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c0d1b6ee |
|
12-May-2016 |
Jonathan Corbet <corbet@lwn.net> |
kernel-doc: produce RestructuredText output If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
fadc0b31 |
|
12-May-2016 |
Jani Nikula <jani.nikula@intel.com> |
kernel-doc: rewrite usage description, remove duplicated comments Instead of having the kernel-doc usage in both comments and in output to the user, merge them all to one here document. While at it, imrove the text and make it pretty. Give shoemaker's children some shoes. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b22b5a9e |
|
08-Nov-2015 |
Conchúr Navid <conchur@web.de> |
kernel-doc: Fix parsing of DECLARE_BITMAP in struct Some documented structures in the kernel use DECLARE_BITMAP to create arrays of unsigned longs to store information using the bitmap functions. These have to be replaced with a parsable version for kernel-doc. For example a simple input like /** * struct something - some test * @members: active members */ struct something { DECLARE_BITMAP(members, MAX_MEMBERS); }; resulted in parsing warnings like warning: No description found for parameter 'MAX_MEMBERS)' warning: Excess struct/union/enum/typedef member 'members' description in 'something' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
4468e21e |
|
08-Nov-2015 |
Conchúr Navid <conchur@web.de> |
kernel-doc: Strip #ifdef/#endif in enums Some enumerations in the kernel headers use #ifdef to reduce their size based on the the configuration. These lines have to be stripped to avoid parsing problems. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag */ enum flags { flag1 = BIT(0), #ifdef SECOND_FLAG flag2 = BIT(1), #endif }; resulted in parsing warnings like warning: Enum value '#ifdef SECOND_FLAG;flag2 = BIT(1)' not described in enum 'flags' warning: Enum value '#endif;' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
8a9260aa |
|
08-Nov-2015 |
Conchúr Navid <conchur@web.de> |
kernel-doc: Fix stripping of #define in enums The regex to strip single line #define's in enumerations depends on the fact that the defines are still stored on separate lines. But the surrounding code already removed newlines and replaced them with semicolons. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag * @flag3: third flag * @flag4: fourth flag */ enum flags { flag1 = BIT(0), flag2 = BIT(1), #define flags_small (flag1 | flag2) flag3 = BIT(2), flag4 = BIT(3), #define flags_big (flag2 | flag3) }; resulted in parsing warnings like warning: Enum value '#define flags_small (flag1 | flag2);flag3 = BIT(2)' not described in enum 'flags' warning: Enum value '#define flags_big (flag2 | flag3);' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
1ef06233 |
|
17-Nov-2015 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
kernel-doc: Make it compatible with Perl versions below 5.12 again Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights hash by an array') broke compatibility of the kernel-doc script with older versions of perl by using "keys ARRAY" syntax with is available only on Perl 5.12 or newer, according with: http://perldoc.perl.org/functions/keys.html Restore backward compatibility by replacing "foreach my $k (keys ARRAY)" by a C-like variant: "for (my $k = 0; $k < !ARRAY; $k++)" Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0d8c39e6 |
|
05-Oct-2015 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
DocBook: Fix kernel-doc to be case-insensitive for private: On some places, people could use Private: to tag the private fields of an struct. So, be case-insensitive when parsing "private:" meta-tag. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
83766452 |
|
08-Oct-2015 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
kernel-doc: better format typedef function output A typedef function looks more likely a function and not a normal typedef. Change the code to use the output_function_*, in order to properly parse the function prototype parameters. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
|
#
3a80a766 |
|
08-Oct-2015 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
kernel-doc: Add a parser for function typedefs The current typedef parser only works for non-function typedefs. As we need to also document some function typedefs, add a parser for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
|
#
4d732701 |
|
07-Sep-2015 |
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> |
scripts/kernel-doc: Replacing highlights hash by an array 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: - @<function>device_for_each_child</function> 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 <danilo.cesar@collabora.co.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
68f86662 |
|
01-Sep-2015 |
Ben Hutchings <ben@decadent.org.uk> |
Documentation: Avoid creating man pages in source tree 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 <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
23aebb3c |
|
01-Sep-2015 |
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> |
scripts/kernel-doc: Processing -nofunc for functions only 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 <danilo.cesar@collabora.co.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
d40e1e65 |
|
04-Sep-2015 |
Bart Van Assche <bvanassche@acm.org> |
kerneldoc: Convert error messages to GNU error message format 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 <bart.vanassche@sandisk.com> Cc: Johannes Berg <johannes.berg@intel.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
f0074929 |
|
23-Aug-2015 |
Jonathan Corbet <corbet@lwn.net> |
kernel-doc: ignore unneeded attribute information 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 <corbet@lwn.net>
|
#
a4c6ebed |
|
04-Aug-2015 |
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> |
scripts/kernel-doc Allow struct arguments documentation in struct body 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 <danilo.cesar@collabora.co.uk> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Herbert Xu <herbert@gondor.apana.org.au> Cc: Stephan Mueller <smueller@chronox.de> Cc: Michal Marek <mmarek@suse.cz> Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx <intel-gfx@lists.freedesktop.org> Cc: dri-devel <dri-devel@lists.freedesktop.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b2c4105b |
|
08-Jul-2015 |
Ben Hutchings <ben@decadent.org.uk> |
scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date Together with the preceding changes, this allows man pages to be built reproducibly. Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
2e106e4d |
|
08-Jul-2015 |
Jérémy Bobbio <lunar@debian.org> |
scripts/kernel-doc: parse kernel-doc deterministically 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 <lunar@debian.org> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7b990789 |
|
10-Dec-2014 |
Johannes Berg <johannes.berg@intel.com> |
scripts/kernel-doc: don't eat struct members with __aligned 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 <johannes.berg@intel.com> Cc: Nishanth Menon <nm@ti.com> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
270a0096 |
|
24-Aug-2014 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: recognize __meminit 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 <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
cbb4d3e6 |
|
12-Jul-2014 |
Horia Geanta <horia.geanta@freescale.com> |
scripts/kernel-doc: handle object-like macros Object-like macros are different than function-like macros: https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html They are not parsed correctly, generating invalid intermediate files (xmls) for cases like: #define BIT_MASK (0xFF << BIT_SHIFT) where "OxFF <<" is considered to be parameter type. When parsing, we can differentiate beween these two types of macros by checking whether there is at least one whitespace b/w "#define" and first opening parenthesis. Signed-off-by: Horia Geanta <horia.geanta@freescale.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
48807e17 |
|
06-Nov-2013 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: make unknown function prototype a Warning instead of an Error When scripts/kernel-doc cannot understand a function prototype, it had been generating a fatal error and stopping immediately. Make this a Warning instead of an Error and keep going. Note that this can happen if the kernel-doc notation that is being parsed is not actually a function prototype; maybe it's a struct or something else, so I added "function" to the warning message to try to make it clearer that scripts/kernel-doc is looking for a function prototype here. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Mark Brown <broonie@kernel.org> Acked-by: Rob Landley <rob@landley.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
|
#
e946c43a |
|
12-Nov-2013 |
Johannes Berg <johannes.berg@intel.com> |
kernel-doc: improve "no structured comments found" error When using '!Ffile function' in a docbook template, and the function no longer exists, you get a "no structured comments found" error from the kernel-doc processing script. It's useful to know which functions it was looking for, so print them out in this case. Also do the same for '!Pfile doc-section' The same error also happens when using '!Efile' when some exported functions aren't documented (in the same file.) There's a very large number of such functions though, so don't print the message in this case -- right now it would give ~850 messages. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Cc: Rob Landley <rob@landley.net> Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
9645ae84 |
|
17-Oct-2013 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: make unknown function prototype a Warning instead of an Error When scripts/kernel-doc cannot understand a function prototype, it had been generating a fatal error and stopping immediately. Make this a Warning instead of an Error and keep going. Note that this can happen if the kernel-doc notation that is being parsed is not actually a function prototype; maybe it's a struct or something else, so I added "function" to the warning message to try to make it clearer that scripts/kernel-doc is looking for a function prototype here. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Mark Brown <broonie@kernel.org> Signed-off-by: Michal Marek <mmarek@suse.cz>
|
#
9dc30918 |
|
27-Feb-2013 |
Nishanth Menon <nm@ti.com> |
scripts/kernel-doc: handle struct member __aligned without numbers Commit ef5da59f1260 ("scripts/kernel-doc: handle struct member __aligned") permits "char something [123] __aligned(8);". However, by using \d we constraint ourselves with integers. This is not always the case. In fact, it might be better to do char something[123] __aligned(sizeof(u16)); For example, With wireless_dev defining: u8 address[ETH_ALEN] __aligned(sizeof(u16)); With \d, scripts/kernel-doc erroneously says: Warning(include/net/cfg80211.h:2618): Excess struct/union/enum/typedef member 'address' description in 'wireless_dev' This is because the regex __aligned\s*\(\d+\) fails match at \d as sizeof is used. So replace \d with . to indicate "something" in kernel-doc to ignore __aligned(SOMETHING) in structs. With this change, we can use integers OR sizeof() or macros as we please. Signed-off-by: Nishanth Menon <nm@ti.com> Cc: Fengguang Wu <fengguang.wu@intel.com> Cc: Johannes Berg <johannes.berg@intel.com> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
6ae14171 |
|
21-Dec-2012 |
Greg Kroah-Hartman <gregkh@linuxfoundation.org> |
misc: remove __dev* attributes. CONFIG_HOTPLUG is going away as an option. As a result, the __dev* markings need to be removed. This change removes the last of the __dev* markings from the kernel from a variety of different, tiny, places. Based on patches originally written by Bill Pemberton, but redone by me in order to handle some of the coding style issues better, by hand. Cc: Bill Pemberton <wfp5p@virginia.edu> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
#
9a52aeeb |
|
27-Nov-2012 |
Yacine Belkadi <yacine.belkadi.1@gmail.com> |
scripts/kernel-doc: check that non-void fcts describe their return value If a function has a return value, but its kernel-doc comment doesn't contain a "Return" section, then emit the following warning: Warning(file.h:129): No description found for return value of 'fct' Note: This check emits a lot of warnings at the moment, because many functions don't have a 'Return' doc section. So until the number of warnings goes sufficiently down, the check is only performed in verbose mode. Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Michal Marek <mmarek@suse.cz>
|
#
4092bac7 |
|
26-Nov-2012 |
Yacine Belkadi <yacine.belkadi.1@gmail.com> |
scripts/kernel-doc: check that non-void fcts describe their return value If a function has a return value, but its kernel-doc comment doesn't contain a "Return" section, then emit the following warning: Warning(file.h:129): No description found for return value of 'fct' Note: This check emits a lot of warnings at the moment, because many functions don't have a 'Return' doc section. So until the number of warnings goes sufficiently down, the check is only performed in verbose mode. Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com> Signed-off-by: Rob Landley <rob@landley.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
|
#
12ae6779 |
|
04-Oct-2012 |
Daniel Santos <daniel.santos@pobox.com> |
kernel-doc: don't mangle whitespace in Example section A section with the name "Example" (case-insensitive) has a special meaning to kernel-doc. These sections are output using mono-type fonts. However, leading whitespace is stripped, thus robbing a lot of meaning from this, as indented code examples will be mangled. This patch preserves the leading whitespace for "Example" sections. More accurately, it preserves it for all sections, but removes it later if the section isn't an "Example" section. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
e314ba31 |
|
04-Oct-2012 |
Daniel Santos <daniel.santos@pobox.com> |
kernel-doc: bugfix - empty line in Example section If you have a section named "Example" that contains an empty line, attempting to generate htmldocs give you the error: /path/Documentation/DocBook/kernel-api.xml:3455: parser error : Opening and ending tag mismatch: programlisting line 3449 and para </para><para> ^ /path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting </programlisting></informalexample> ^ /path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para </para><para> ^ /path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting </programlisting></informalexample> ^ unable to parse /path/Documentation/DocBook/kernel-api.xml Essentially, the script attempts to close a <programlisting> with a closing tag for a <para> block. This patch corrects the problem by simply not outputting anything extra when we're dumping pre-formatted text, since the empty line will be rendered correctly anyway. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
65478428 |
|
04-Oct-2012 |
Daniel Santos <daniel.santos@pobox.com> |
kernel-doc: bugfix - multi-line macros Prior to this patch the following code breaks: /** * multiline_example - this breaks kernel-doc */ #define multiline_example( \ myparam) Producing this error: Error(somefile.h:983): cannot understand prototype: 'multiline_example( \ ' This patch fixes the issue by appending all lines ending in a blackslash (optionally followed by whitespace), removing the backslash and any whitespace after it prior to appending (just like the C pre-processor would). This fixes a break in kerel-doc introduced by the additions to rbtree.h. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
1b40c194 |
|
12-Aug-2012 |
Dan Luedtke <mail@danrl.de> |
scripts/kernel-doc: added support for html5 New output option html5 writes validating HTML5 and adds CSS classes ready to be selected by third-party stylesheets. HTML ids have been added to block-level elements "article" for direct reference of particular objects via URL. Signed-off-by: Dan Luedtke <mail@danrl.de> Acked-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Michal Marek <mmarek@suse.cz>
|
#
0df7c0e3 |
|
16-Aug-2012 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: fix fatal script error Fix fatal error in scripts/kernel-doc by ignoring the "__weak" attribute: Error(drivers/pci/pci.c:2820): cannot understand prototype: 'char * __weak pcibios_setup(char *str) ' Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
70c95b00 |
|
21-Jan-2012 |
Randy Dunlap <rdunlap@infradead.org> |
scripts/kernel-doc: fix fatal error caused by cfg80211.h include/net/cfg80211.h uses __must_check in functions that have kernel-doc notation. This was confusing scripts/kernel-doc, so have scripts/kernel-doc ignore "__must_check". Error(include/net/cfg80211.h:2702): cannot understand prototype: 'struct cfg80211_bss * __must_check cfg80211_inform_bss(...) Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Cc: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
25985edc |
|
30-Mar-2011 |
Lucas De Marchi <lucas.demarchi@profusion.mobi> |
Fix common misspellings Fixes generated by 'codespell' and manually reviewed. Signed-off-by: Lucas De Marchi <lucas.demarchi@profusion.mobi>
|
#
8484baaa |
|
05-Jan-2011 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: code reorganization Move 'main' code vs. subroutines around so that they are not so intermixed, for better readability/understanding (relative to Perl). It was messy to follow the primary flow of code execution with the code being mixed. Now the code begins with data initialization, followed by all subroutines, then ends with the main code execution. This is almost totally source code movement, with a few changes as needed for forward declarations. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
2b35f4d9 |
|
18-Nov-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: escape xml for structs scripts/kernel-doc was leaving unescaped '<', '>', and '&' in generated xml output for structs. This causes xml parser errors. Convert these characters to "<", ">", and "&" as needed to prevent errors. Most of the conversion was already done; complete it just before output. Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name #define INPUT_KEYMAP_BY_INDEX (1 << 0) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
eda603f6 |
|
11-Sep-2010 |
Johannes Berg <johannes.berg@intel.com> |
docbook: warn on unused doc entries When you don't use !E or !I but only !F, then it's very easy to miss including some functions, structs etc. in documentation. To help finding which ones were missed, allow printing out the unused ones as warnings. For example, using this on mac80211 yields a lot of warnings like this: Warning: didn't use docs for DOC: mac80211 workqueue Warning: didn't use docs for ieee80211_max_queues Warning: didn't use docs for ieee80211_bss_change Warning: didn't use docs for ieee80211_bss_conf when generating the documentation for it. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
1f3a6688 |
|
11-Sep-2010 |
Johannes Berg <johannes.berg@intel.com> |
kernel-doc: ignore case when stripping attributes There are valid attributes that could have upper case letters, but we still want to remove, like for example __attribute__((aligned(NETDEV_ALIGN))) as encountered in the wireless code. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
b6d676db |
|
10-Aug-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
mtd/nand_base: fix kernel-doc warnings & typos Fix mtd/nand_base.c kernel-doc warnings and typos. Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: David Woodhouse <dwmw2@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
db9ebb7c |
|
24-May-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
mtd/nand_base: fix kernel-doc warnings & typos Fix mtd/nand_base.c kernel-doc warnings and typos. Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs' Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len' Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: David Woodhouse <David.Woodhouse@intel.com>
|
#
20072205 |
|
23-Mar-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
scripts/kernel-doc: fix fatal error on function prototype Fix a fatal error in scripts/kernel-doc when a function signature uses __init_or_module (just ignore that string): Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) ' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
ef5da59f |
|
23-Mar-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
scripts/kernel-doc: handle struct member __aligned scripts/kernel-doc erroneously says: Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff' on this line in struct sk_buff: char cb[48] __aligned(8); due to treating the last field as the struct member name, so teach kernel-doc to ignore __aligned(x) in structs. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
4c98ecaf |
|
10-Mar-2010 |
Randy Dunlap <randy.dunlap@oracle.com> |
scripts/kernel-doc: fix empty function description section scripts/kernel-doc mishandles a function that has a multi-line function short description and no function parameters. The observed problem was from drivers/scsi/scsi_netlink.c: /** * scsi_netlink_init - Called by SCSI subsystem to intialize * the SCSI transport netlink interface * **/ kernel-doc treated the " * " line as a Description: section with only a newline character in the Description contents. This caused output_highlight() to complain: "output_highlight got called with no args?", plus produce a perl call stack backtrace. The fix is just to ignore Description sections if they only contain "\n". Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
1c32fd0c |
|
26-Feb-2010 |
Ilya Dryomov <idryomov@gmail.com> |
kernel-doc: drop the -filelist option, it doesn't work I also found the -filelist option, but apparently the implementation is broken, and it was broken from the very first git commit. For the -filelist option I suggest the removal (I wasn't able to find any users of it, moreover it's not even listed in the usage() output, so presumably nobody knows about it). Signed-off-by: Ilya Dryomov <idryomov@gmail.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
a9e7314b |
|
26-Feb-2010 |
Ilya Dryomov <idryomov@gmail.com> |
kernel-doc: track line numbers for each file separately The problem is that $. keeps track of the current record number (which is line number by default). But if you pass it multiple files, it does not wrap at the end of file, and therefore contains the *total* number of processed lines. I suppose we can fix line numbering by introducing a simple assignment $. = 1 before processing every new file. Signed-off-by: Ilya Dryomov <idryomov@gmail.com> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
3a9089fd |
|
30-Nov-2009 |
Jason Baron <jbaron@redhat.com> |
tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook style comments that used to live with 'TRACE_EVENT()' are now moved to 'DEFINE_EVENT()'. Thus, we need to make the docbook system understand the new 'DEFINE_EVENT()' macro. In addition I've tried to futureproof the patch, by also adding support for 'DEFINE_SINGLE_EVENT()', since there has been discussion about renaming: TRACE_EVENT() -> DEFINE_SINGLE_EVENT(). Without this patch the tracepoint docbook fails to build. I've verified that this patch correctly builds the tracepoint docbook which currently covers signals, and irqs. Changes in v2: - properly indent perl 'if' statements Signed-off-by: Jason Baron <jbaron@redhat.com> Acked-by: Steven Rostedt <rostedt@goodmis.org> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: William Cohen <wcohen@redhat.com> Cc: Frederic Weisbecker <fweisbec@gmail.com> Cc: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca> Cc: Masami Hiramatsu <mhiramat@redhat.com> LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com> Signed-off-by: Ingo Molnar <mingo@elte.hu>
|
#
6423133b |
|
17-Sep-2009 |
Johannes Weiner <hannes@cmpxchg.org> |
kernel-doc: allow multi-line declaration purpose descriptions Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this: /** * unmap_mapping_range - unmap the portion of all mmaps in the * specified address_space corresponding to the specified * page range in the underlying file. * @mapping: the address space containing mmaps to be unmapped. * ... */ The short description ends with a parameter description, an empty line or the end of the comment block. Signed-off-by: Johannes Weiner <hannes@cmpxchg.org> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
d960eea9 |
|
29-Jun-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: move ignoring kmemcheck Somehow I managed to generate a diff that put these 2 lines into the wrong function: should have been in dump_struct() instead of in dump_enum(). Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
e34e7dbb |
|
17-Jun-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix param matching for array params Fix function actual parameter vs. kernel-doc description matching so that a warning is not printed when it should not be: Warning(include/linux/etherdevice.h:199): Excess function parameter 'addr' description in 'is_etherdev_addr' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
b2fd6dbf |
|
17-Jun-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: ignore kmemcheck_bitfield_begin/end Teach kernel-doc to ignore kmemcheck_bitfield_{begin,end} sugar so that it won't generate warnings like this: Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_begin(flags)' Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_end(flags)' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
b9d97328 |
|
09-Jun-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: cleanup perl script Various cleanups of scripts/kernel-doc: - don't use **/ as an ending kernel-doc block since it's not preferred; - typos/spellos - add whitespace around ==, after comma, & around . operator; Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
52dc5aec |
|
30-Apr-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: restrict syntax for private: and public: scripts/kernel-doc can (incorrectly) delete struct members that are surrounded by /* ... */ <struct members> /* ... */ if there is a /* private: */ comment in there somewhere also. Fix that by making the "/* private:" only allow whitespace between /* and "private:", not anything/everything in the world. This fixes some erroneous kernel-doc warnings that popped up while processing include/linux/usb/composite.h. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
56afb0f8 |
|
30-Apr-2009 |
Jason Baron <jbaron@redhat.com> |
kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2) Add support to kernel-doc for tracepoint comments above TRACE_EVENT() macro definitions. Paves the way for tracepoint docbook. [ Impact: extend DocBook infrastructure ] Signed-off-by: Jason Baron <jbaron@redhat.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: akpm@linux-foundation.org Cc: rostedt@goodmis.org Cc: fweisbec@gmail.com Cc: mathieu.desnoyers@polymtl.ca Cc: wcohen@redhat.com LKML-Reference: <d80706b6797e277924d2f3ec9af176c6b2951f88.1241107197.git.jbaron@redhat.com> Signed-off-by: Ingo Molnar <mingo@elte.hu>
|
#
b4870bc5 |
|
11-Feb-2009 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix syscall wrapper processing Fix kernel-doc processing of SYSCALL wrappers. The SYSCALL wrapper patches played havoc with kernel-doc for syscalls. Syscalls that were scanned for DocBook processing reported warnings like this one, for sys_tgkill: Warning(kernel/signal.c:2285): No description found for parameter 'tgkill' Warning(kernel/signal.c:2285): No description found for parameter 'pid_t' Warning(kernel/signal.c:2285): No description found for parameter 'int' because the macro parameters all "look like" function parameters, although they are not: /** * sys_tgkill - send signal to one specific thread * @tgid: the thread group ID of the thread * @pid: the PID of the thread * @sig: signal to be sent * * This syscall also checks the @tgid and returns -ESRCH even if the PID * exists but it's not belonging to the target process anymore. This * method solves the problem of threads exiting and PIDs getting reused. */ SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig) { ... This patch special-cases the handling SYSCALL_DEFINE* function prototypes by expanding them to long sys_foobar(type1 arg1, type1 arg2, ...) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
a1d94aa5 |
|
19-Dec-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: check for extra kernel-doc notations Add functionality to check for function parameters or structure (or union/typedef/enum) field members that are described in kernel-doc but are not part of the expected (declared) parameters or structure. These generate warnings that are called "Excess" descriptions. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
ced69090 |
|
01-Dec-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: handle varargs cleanly The method for listing varargs in kernel-doc notation is: * @...: these arguments are printed by the @fmt argument but scripts/kernel-doc is confused: it always lists varargs as: ... variable arguments and ignores the @...: line's description, but then prints that line after the list of function parameters as though it's not part of the function parameters. This patch makes kernel-doc print the supplied @... description if it is present; otherwise a boilerplate "variable arguments" is printed. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
890c78c2 |
|
25-Oct-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: allow more whitespace in macros Allow macros that are annotated with kernel-doc to contain whitespace between the '#' and "define". It's valid and being used, so allow it. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
39f00c08 |
|
22-Sep-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: allow structs whose members are all private Struct members may be marked as private by using /* private: */ before them, as noted in Documentation/kernel-doc-nano-HOWTO.txt Fix kernel-doc to handle structs whose members are all private; otherwise invalid XML is generated: xmlto: input does not validate (status 3) linux-2.6.27-rc6-git4/Documentation/DocBook/debugobjects.xml:146: element variablelist: validity error : Element variablelist content does not follow the DTD, expecting ((title , titleabbrev?)? , varlistentry+), got () Document linux-2.6.27-rc6-git4/Documentation/DocBook/debugobjects.xml does not validate make[1]: *** [Documentation/DocBook/debugobjects.html] Error 3 Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Reported-by: Roland McGrath <roland@redhat.com> Cc: Roland McGrath <roland@redhat.com> Cc: Christoph Hellwig <hch@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
32ab8f97 |
|
05-Aug-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: skip nested struct/union cleanly Fix handling of nested structs or unions. The regex to strip (eliminate) nested structs or unions was limited to only 0 or 1 matches. This can cause an uneven number of left/right braces to be stripped, which causes this: Warning(linux-2.6.27-rc1-git2//include/net/mac80211.h:336): No description found for parameter '}' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
74fc5c65 |
|
19-Jun-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: handle/strip __init Handle __init in functions with kernel-doc notation by stripping the __init away from the output doc. This is already being done for "__devinit". This patch fixes these kernel-doc error/aborts: Error(linux-next-20080619//drivers/usb/gadget/config.c:132): cannot understand prototype: 'struct usb_descriptor_header **__init usb_copy_descriptors(struct usb_descriptor_header **src) ' Error(linux-next-20080619//drivers/usb/gadget/config.c:182): cannot understand prototype: 'struct usb_endpoint_descriptor *__init usb_find_endpoint( struct usb_descriptor_header **src, struct usb_descriptor_header **copy, struct usb_endpoint_descriptor *match ) ' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
7b97887e |
|
16-May-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: allow unnamed bit-fields Allow for unnamed bit-fields and skip them instead of printing an erroneous warning message for them, such as: Warning(include/asm-s390/cio.h:103): No description found for parameter 'u32' which contains: struct tm_scsw { u32 :1; Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
46b958eb |
|
28-Apr-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: detect trailing kernel-doc line trash Print a warning when a kernel-doc comment block ends with text on the same line as the ending comment characters, e.g.: * this text is lost. */ Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
94dc7ad5 |
|
28-Apr-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: detect/prevent duplicate doc section names I saw this problem recently. With this kernel-doc: * Note: some important info * * Note: other important info kernel-doc uses the "section name" (preceding the ':', like "Note") as a hash key for storing the descriptive text ("blah important info"). It is (was) possible to have duplicate (colliding) section names, without any kind of warning or error. kernel-doc happily used the latter descriptive text for all instances of printing the <section-name> descriptive text and the former important info was lost. One way to "fix" this is to modify the kernel-doc comments, e.g.: * Note1: foo bar * * Note.2: blah zay For now, kernel-doc will signal an error when it sees colliding section names like this. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
bd0e88e5 |
|
13-Mar-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: set verbose mode via environment Honor the environment variable "KBUILD_VERBOSE=1" (as set by make V=1) to enable verbose mode in scripts/kernel-doc. Useful for getting more info and warnings from kernel-doc. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: Sam Ravnborg <sam@ravnborg.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
00d62961 |
|
23-Feb-2008 |
Richard Kennedy <richard@rsk.demon.co.uk> |
kernel-doc: fix function-pointer-parameter parsing When running "make htmldocs" I'm seeing some non-fatal perl errors caused by trying to parse the callback function definitions in blk-core.c. The errors are "Use of uninitialized value in concatenation (.)..." in combination with: Warning(linux-2.6.25-rc2/block/blk-core.c:1877): No description found for parameter '' The function pointers are defined without a * i.e. int (drv_callback)(struct request *) The compiler is happy with them, but kernel-doc isn't. This patch teaches create_parameterlist in kernel-doc to parse this type of function pointer definition, but is it the right way to fix the problem ? The problem only seems to occur in blk-core.c. However with the patch applied, kernel-doc finds the correct parameter description for the callback in blk_end_request_callback, which is doesn't normally. I thought it would be a bit odd to change to code to use the more normal form of function pointers just to get the documentation to work, so I fixed kernel-doc instead - even though this is teaching it to understand code that might go away (The comment for blk_end_request_callback says that it should not be used and will removed at some point). Signed-off-by: Richard Kennedy <richard@rsk.demon.co.uk> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
34ff8a52 |
|
14-Feb-2008 |
Harvey Harrison <harvey.harrison@gmail.com> |
kernel-doc: remove fastcall fastcall is gone from the tree, no need to adjust the function prototypes anymore for this. Signed-off-by: Harvey Harrison <harvey.harrison@gmail.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
77cc23b8 |
|
07-Feb-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: warn on badly formatted short description Make kernel-doc warn when a function/struct/union/typedef does not contain a properly formatted short description, such as: * scsi_devinfo: set up the dynamic device list or * scsi_devinfo - This warning is only generated when verbose (-v) mode is used. Also explain the -v command line option in the -h output. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
792aa2f2 |
|
07-Feb-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: prevent duplicate description: output Prevent duplicate output of a Description: section when there is a "blank" ("*") line between the initial function name/description line and the "Description:" header. Test case: drivers/scsi/scsi_devinfo.c::scsi_init_devinfo(). Rob Landley hit this while he was producing SCSI kernel-doc. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
94b3e03c |
|
07-Feb-2008 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix for vunmap function prototype Fix kernel-doc function prototype parsing which was exposed by vunmap() by allowing more than one '*' before the function name. Error(linux-2.6.24-mm1//mm/vmalloc.c:438): cannot understand prototype: 'struct page **vunmap(const void *addr) ' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
4b44595a |
|
24-Oct-2007 |
Johannes Berg <johannes@sipsolutions.net> |
kernel-doc: process functions, not DOC: This flag is necessary for the next patch for docproc to output only the functions and not DOC: sections when a function list is requested. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
b112e0f7 |
|
24-Oct-2007 |
Johannes Berg <johannes@sipsolutions.net> |
kernel-doc: single DOC: selection Currently, DOC: sections are always output even if only a single function is requested, fix this and also make it possible to just output a single DOC: section by giving its title as the function name to output. Also fixes docbook XML well-formedness for sections with examples. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
1b9bc22d |
|
24-Oct-2007 |
Johannes Berg <johannes@sipsolutions.net> |
kernel-doc: init kernel version The kernel-doc script triggers a perl warning when invoked without KERNELVERSION in the environment, rather make it use the string "unknown kernel version" instead. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
5c98fc03 |
|
24-Oct-2007 |
Johannes Berg <johannes@sipsolutions.net> |
kernel-doc: fix xml output mode After Randy's patch fixing the HTML output in DOC: sections (6b5b55f6c404fa730a09a8254eb19f5a038afcc2) the same bug remained in XML mode, this fixes it. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
6b5b55f6 |
|
17-Oct-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix doc blocks and html Johannes Berg reports (Thanks!) that &struct names are not highlighted in html output format when they are inside a DOC: block. DOC: blocks were not escaped thru xml_escape() like other kernel-doc comments were. Fixed that. However, that left a problem with <p> ($blankline_html) being processed thru xml_escape(), converting it to <p>, which isn't good for the generated html output (the <p> should remain unchanged), so this patch also introduces the notion of "local" kernel-doc meta-characters ('\\\\mnemonic:'), which are converted to html just before writing the stream to its output file. Please report any problems that you (anyone) see in "highlighting" in any output mode (text, man, html, xml). Also update copyright to include me. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
cdccb316 |
|
19-Jul-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix leading dot in man-mode output If a parameter description begins with a '.', this indicates a "request" for "man" mode output (*roff), so it needs special handling. Problem case is in include/asm-i386/atomic.h for function atomic_add_unless(): * @u: ...unless v is equal to u. This parameter description is currently not printed in man mode output. [akpm@linux-foundation.org: cleanup] Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
51f5a0c8 |
|
19-Jul-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: strip C99 comments Strip C99-style comments from the input stream. /*...*/ comments are already stripped. C99 comments confuse the kernel-doc script. Also update some comments. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
5f8c7c98 |
|
19-Jul-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: fix unnamed struct/union warning Fix kernel-doc warning: Warning(linux-2.6.22-rc2-git2/include/linux/skbuff.h:316): No description found for parameter '}' which is caused by nested anonymous structs/unions ending with: }; }; Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
0366299b |
|
09-May-2007 |
Borislav Petkov <bbpetkov@yahoo.de> |
kernel-doc: small kernel-doc optimization Get the kernel version string only once from the environment, thus slightly speeding up kernel-doc. Signed-off-by: Borislav Petkov <bbpetkov@yahoo.de> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
53f049fa |
|
08-May-2007 |
Borislav Petkov <bbpetkov@yahoo.de> |
kill warnings when building mandocs This patch shuts warnings of the sort: make -C /mnt/samsung_200/sam/kernel/trees/21-rc6/build \ KBUILD_SRC=/mnt/samsung_200/sam/kernel/trees/21-rc6 \ KBUILD_EXTMOD="" -f /mnt/samsung_200/sam/kernel/trees/21-rc6/Makefile mandocs make -f /mnt/samsung_200/sam/kernel/trees/21-rc6/scripts/Makefile.build obj=scripts/basic make -f /mnt/samsung_200/sam/kernel/trees/21-rc6/scripts/Makefile.build obj=Documentation/DocBook mandocs SRCTREE=/mnt/samsung_200/sam/kernel/trees/21-rc6/ /mnt/samsung_200/sam/kernel/trees/21-rc6/build/scripts/basic/docproc doc /mnt/samsung_200/sam/kernel/trees/21-rc6/Documentation/DocBook/wanbook.tmpl >Documentation/DocBook/wanbook.xml if grep -q refentry Documentation/DocBook/wanbook.xml; then xmlto man -m /mnt/samsung_200/sam/kernel/trees/21-rc6/Documentation/DocBook/stylesheet.xsl -o Documentation/DocBook/man Documentation/DocBook/wanbook.xml ; gzip -f Documentation/DocBook/man/*.9; fi Note: meta version: No productnumber or alternative sppp_close Note: meta version: No refmiscinfo@class=version sppp_close Note: Writing sppp_close.9 Note: meta version: No productnumber or alternative sppp_open Note: meta version: No refmiscinfo@class=version sppp_open by adding a RefMiscInfo xml tag in the form of the current kernel version to the function, struct and enum definitions in files included by kernel-doc when building 'mandocs'. However, the version string appears truncated on the manpage due to some constraints in the xml DTD for the man header, I believe, for the troff output is truncated too. Signed-off-by: Borislav Petkov <bbpetkov@yahoo.de> Cc: "Randy.Dunlap" <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
3eb014a1 |
|
08-May-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
kernel-doc: html mode struct highlights Johannes Berg reported that struct names are not highlighted (bold, italic, etc.) in html kernel-doc output. (Also not in text-mode output, but I don't see that changing.) This patch adds the following: - highlight struct names in html output mode - highlight environment var. names in html output mode - indent struct fields in the original struct layout Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Cc: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
884f2810 |
|
08-May-2007 |
Borislav Petkov <bbpetkov@yahoo.de> |
kernel-doc: handle arrays with arithmetic expressions as initializers In a different approach here's a patch that handles the special case of composite arithmetic expressions in array size initializers. With it, prior to pushing the split strings on the @first_arg array, I split the keywords before the array name as before and then keep the array name along with the subscript expression as a single whole element which gets pushed last. In this manner, kernel-doc produces correct output without removing whitespaces which makes the array subscripts unreadable in the docs. Signed-off-by: Borislav Petkov <bbpetkov@yahoo.de> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
3c308798 |
|
08-May-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
scripts: kernel-doc whitespace cleanup Whitespace cleanup only: convert some series of spaces to tabs. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
328d2440 |
|
28-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: allow space after __attribute__ Allow space(s) between "__attribute__" and "((blah))" so that kernel-doc does not complain like: Warning(/tester/linsrc/linux-2.6.20-git15//kernel/timer.c:939): No description found for parameter 'read_persistent_clock(void' Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
262d9b01 |
|
20-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: include struct short description in title output Output of a function or struct in html mode needs to include the short description from the function/struct name line in the output title line. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Acked-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
412ecd77 |
|
10-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] fix fatal kernel-doc error Teach kernel-doc to handle functions that look like the new pcim_iomap_table(). Fixes this fatal error in scripts/kernel-doc: DOCPROC Documentation/DocBook/kernel-api.xml Error(/tester/linsrc/linux-2.6.20-git6//drivers/pci/pci.c:1351): cannot understand prototype: 'void __iomem * const * pcim_iomap_table(struct pci_dev *pdev) ' make[1]: *** [Documentation/DocBook/kernel-api.xml] Error 1 make: *** [htmldocs] Error 2 Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
a21217da |
|
10-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: fix some odd spacing issues - in man and text mode output, if the function return type is empty (like it is for macros), don't print the return type and a following space; this fixes an output malalignment; - in the function short description, strip leading, trailing, and multiple embedded spaces (to one space); this makes function name/description output spacing consistent; - fix a comment typo; Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
996a07bc |
|
10-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: allow more whitespace Allow whitespace in pointer-to-function [accept "(* done)", not just "(*done)"]. Allow tabs (spaces are already allowed) between "#define" and a macro name. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
891dcd2f |
|
10-Feb-2007 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: allow a little whitespace In kernel-doc syntax, be a little flexible: allow whitespace between a function parameter name and the colon that must follow it, such as: @pdev : PCI device to unplug (This allows lots of megaraid kernel-doc to work without tons of editing.) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
5449bc94 |
|
10-Feb-2007 |
Pavel Pisa <pisa@cmp.felk.cvut.cz> |
[PATCH] DocBook/HTML: correction of recursive A tags in HTML output The malformed HTML was generated after switch to XSLTPROC from SGML tools. The reference title <refentrytitle><phrase id="API-struct-x">struct x</phrase></refentrytitle> is converted into two recursive <a> tags <a href="re02.html"><span><a id="API-struct-x"></a>struct x</span></a> There is more possible solutions for this problem. One can be found at http://darkk.livejournal.com/ The proposed solution is based on suggestion provided by Jiri Kosek. Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
|
#
134fe01b |
|
22-Dec-2006 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: allow unnamed structs/unions Make kernel-doc support unnamed (anonymous) structs and unions. There is one (union) in include/linux/skbuff.h (inside struct sk_buff) that is currently generating a kernel-doc warning, so this fixes that warning. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
ea82c740 |
|
06-Dec-2006 |
Randy Dunlap <randy.dunlap@oracle.com> |
[PATCH] kernel-doc: stricter function pointer recognition Be more careful about function pointer args: look for "(...*" instead of just "(". This line in include/linux/input.h fools the current kernel-doc script into deciding that this is a function pointer: unsigned long ffbit[NBITS(FF_MAX)]; Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
27205744 |
|
11-Oct-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: make parameter description indentation uniform - In parameter descriptions, strip all whitespace between the parameter name (e.g., @len) and its description so that the description is indented uniformly in text and man page modes. Previously, spaces or tabs (which are used for cleaner source code viewing) affected the produced output in a negative way. Before (man mode): to Destination address, in user space. from Source address, in kernel space. n Number of bytes to copy. After (man mode): to Destination address, in user space. from Source address, in kernel space. n Number of bytes to copy. - Fix/clarify a few function description comments. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
32e79401 |
|
11-Oct-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: drop various "inline" qualifiers Drop __inline, __always_inline, and noinline in the produced kernel-doc output, similar to other pseudo directives. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
a073a8bd |
|
03-Oct-2006 |
Rolf Eike Beer <eike-kernel@sf-tec.de> |
Fix copy&waste bug in comment in scripts/kernel-doc This is obviously copied from some lines before without proper fixing. Signed-off-by: Rolf Eike Beer <eike-kernel@sf-tec.de> Acked-by: Alan Cox <alan@redhat.com> Signed-off-by: Adrian Bunk <bunk@stusta.de>
|
#
0129a057 |
|
30-Jul-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: ignore __devinit Ignore __devinit in function definitions so that kernel-doc won't fail on them. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
f47634b2 |
|
01-Jul-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: make man/text mode function output same Make output of function descriptions in text mode match contents of 'man' mode by adding Name: plus function-short-description ("purpose") and changing Function: to Synopsis:. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
1d7e1d45 |
|
01-Jul-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: consistent text/man mode output Add a space between data type and struct field name in man-mode bitfield struct output so that they don't run together. For text-mode struct output, print the struct 'purpose' or short description (as done in man-mode output). For text-mode enum output, print the enum 'purpose' or short description (as done in man-mode output). For text-mode typedef output, print the typedef 'purpose' or short description (as done in man-mode output). Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
c51d3dac |
|
25-Jun-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: use Members for struct fields consistently kernel-doc struct fields should be consistently called "Members", not "Arguments", so switch man-mode output to use "Members" like all of the other formats do. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
ecfb251a |
|
25-Jun-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: don't use XML escapes in text or man output mode For kernel-doc output modes of text and man, do not use XML escapes for less-than, greater-than, and ampersand characters. I.e., leave the text and man output clean and readable. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
850622df |
|
25-Jun-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: warn on malformed function docs. When the verbose (-v) option is used with scripts/kernel-doc, this option reports when the kernel-doc format is malformed and apparently contains function description lines before function parameters. In these cases, the kernel-doc script will print something like: Warning(filemap.c:335): contents before sections I have fixed the problems in mm/filemap.c and added lots of kernel-doc to that file (posted to the linux-mm mailing list Mon. 2006-June-12). The real goal (as requested by Andrew Morton) is to allow the short function description to be more than one line long. This patch is both a kernel-doc checker and a tool en route to that goal. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
232acbcf |
|
25-Jun-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: script cleanups Fix indentation. Quote a brace '{' so that vi won't be fooled by it. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
05189497 |
|
25-Jun-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: drop leading space in sections Drop leading space of kernel-doc section contents. "Section" data (contents) are split from the section header (e.g., Note: below is a section header: * Note: list_empty on entry does not return true after this, the entry is * in an undefined state. ). Currently the data/contents begins with a space and is left that way, which causes it to look bad when printed (in text mode; see example below), so just remove the leading space. Note: list_empty on entry does not return true after this, the entry is in an undefined state. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
3c3b809e |
|
01-Feb-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] kernel-doc: clean up the script (whitespace) Remove lots of trailing whitespace. Nothing else. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
d28bee0c |
|
01-Feb-2006 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] Doc/kernel-doc: add more usage info - Add info that structs, unions, enums, and typedefs are supported. - Add doc about "private:" and "public:" tags for struct fields. - Fix some typos. - Remove some trailing whitespace. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
9598f91f |
|
01-Feb-2006 |
Martin Waitz <tali@admingilde.org> |
[PATCH] DocBook: allow even longer return types kernel-doc errored out because it could not understand the new __copy_to_user definition. Now we allow return types with four words. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
a6d3fe77 |
|
09-Jan-2006 |
Martin Waitz <tali@admingilde.org> |
[PATCH] DocBook: warn for missing macro parameters Previously kernel-doc silently ignored missing parameter descriptions for preprocessor macros. Now that all such omissions are fixed up we can warn about them in kernel-doc to be able to keep it that way. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
aeec46b9 |
|
13-Nov-2005 |
Martin Waitz <tali@admingilde.org> |
[PATCH] DocBook: allow to mark structure members private Many structures contain both an internal part and one which is part of the API to other modules. With this patch it is possible to only include these public members in the kernel documentation. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
2283a117 |
|
07-Jul-2005 |
Randy Dunlap <rdunlap@infradead.org> |
[PATCH] scripts/kernel-doc: don't use uninitialized SRCTREE Current kernel-doc (perl) script generates this warning: Use of uninitialized value in concatenation (.) or string at scripts/kernel-doc line 1668. So explicitly check for SRCTREE in the ENV before using it, and then if it is set, append a '/' to the end of it, otherwise the SRCTREE + filename can (will) be missing the intermediate '/'. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
|
#
8b0c2d98 |
|
01-May-2005 |
Martin Waitz <tali@admingilde.org> |
[PATCH] DocBook: Use xmlto to process the DocBook files. xmlto uses standared XSLT templates to generate manpages, (x)html pages, and XML FO files which can be processed with passivetex. This is much faster than using jadetex for everything. This patch also reduces the number of kernel-specific scripts that are needed to generate documentation. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
c73894c1 |
|
01-May-2005 |
Rich Walker <rw@shadow.org.uk> |
[PATCH] DocBook: use <informalexample> for examples Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
6013d544 |
|
01-May-2005 |
Martin Waitz <tali@admingilde.org> |
[PATCH] DocBook: fix <void/> xml tag This fix is needed to create valid XML. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
4dc3b16b |
|
01-May-2005 |
Pavel Pisa <pisa@cmp.felk.cvut.cz> |
[PATCH] DocBook: changes and extensions to the kernel documentation I have recompiled Linux kernel 2.6.11.5 documentation for me and our university students again. The documentation could be extended for more sources which are equipped by structured comments for recent 2.6 kernels. I have tried to proceed with that task. I have done that more times from 2.6.0 time and it gets boring to do same changes again and again. Linux kernel compiles after changes for i386 and ARM targets. I have added references to some more files into kernel-api book, I have added some section names as well. So please, check that changes do not break something and that categories are not too much skewed. I have changed kernel-doc to accept "fastcall" and "asmlinkage" words reserved by kernel convention. Most of the other changes are modifications in the comments to make kernel-doc happy, accept some parameters description and do not bail out on errors. Changed <pid> to @pid in the description, moved some #ifdef before comments to correct function to comments bindings, etc. You can see result of the modified documentation build at http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.11.tar.gz Some more sources are ready to be included into kernel-doc generated documentation. Sources has been added into kernel-api for now. Some more section names added and probably some more chaos introduced as result of quick cleanup work. Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
|
#
1da177e4 |
|
16-Apr-2005 |
Linus Torvalds <torvalds@ppc970.osdl.org> |
Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
|