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

kernel-doc: handle #if in enums as well

2024-02-21T20:44:21+00:00

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240214142937.80ee86a3beae.Ibcc5bd97a20cd10a792663e4b254cd46c7e8b520@changeid

scripts/kernel-doc: simplify signature printing

2024-02-21T20:44:21+00:00

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-5-vegard.nossum@oracle.com

scripts/kernel-doc: separate out function signature

2024-02-21T20:44:21+00:00

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-4-vegard.nossum@oracle.com

scripts/kernel-doc: simplify function printing

2024-02-21T20:44:21+00:00

Get rid of the $start variable, since it's really not necessary. No functional change. Signed-off-by: Vegard Nossum Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-3-vegard.nossum@oracle.com

scripts/kernel-doc: add modeline for vim users

2024-02-21T20:44:21+00:00

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 Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-2-vegard.nossum@oracle.com

scripts/kernel-doc: reindent

2024-02-14T22:33:23+00:00

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 Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240208161705.888385-1-vegard.nossum@oracle.com

kernel-doc: Support arrays of pointers struct fields

2024-02-05T16:53:02+00:00

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 Acked-by: Randy Dunlap Tested-by: Randy Dunlap Tested-by: Ricardo Ribalda Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240131084934.191226-1-sakari.ailus@linux.intel.com

kernel-doc: drop looking for "MACDOC"

2024-01-30T20:31:04+00:00

Linux kernel does not use "MACDOC" in any documenation or any source files, so stop searching for it. Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240108003700.13418-1-rdunlap@infradead.org

scripts/kernel-doc: Do not process backslash lines in comments

2024-01-30T20:03:01+00:00

To prevent this, do the pre-processing only for lines which are no comments, e.g. do not start with ' *'. Suggested-by: Matthew Wilcox Signed-off-by: Anna-Maria Behnsen Tested-by: Randy Dunlap Acked-by: Daniel Vetter Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240122093152.22536-3-anna-maria@linutronix.de

Merge tag 'docs-6.8' of git://git.lwn.net/linux

2024-01-12T03:46:52+00:00

Pull documentation update from Jonathan Corbet: "Another moderately busy cycle for documentation, including: - The minimum Sphinx requirement has been raised to 2.4.4, following a warning that was added in 6.2 - Some reworking of the Documentation/process front page to, hopefully, make it more useful - Various kernel-doc tweaks to, for example, make it deal properly with __counted_by annotations - We have also restored a warning for documentation of nonexistent structure members that disappeared a while back. That had the delightful consequence of adding some 600 warnings to the docs build. A sustained effort by Randy, Vegard, and myself has addressed almost all of those, bringing the documentation back into sync with the code. The fixes are going through the appropriate maintainer trees - Various improvements to the HTML rendered docs, including automatic links to Git revisions and a nice new pulldown to make translations easy to access - Speaking of translations, more of those for Spanish and Chinese ... plus the usual stream of documentation updates and typo fixes" * tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits) MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL A reworked process/index.rst ring-buffer/Documentation: Add documentation on buffer_percent file Translated the RISC-V architecture boot documentation. Docs: remove mentions of fdformat from util-linux Docs/zh_CN: Fix the meaning of DEBUG to pr_debug() Documentation: move driver-api/dcdbas to userspace-api/ Documentation: move driver-api/isapnp to userspace-api/ Documentation/core-api : fix typo in workqueue Documentation/trace: Fixed typos in the ftrace FLAGS section kernel-doc: handle a void function without producing a warning scripts/get_abi.pl: ignore some temp files docs: kernel_abi.py: fix command injection scripts/get_abi: fix source path leak CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer docs: translations: add translations links when they exist kernel-doc: Align quick help and the code MAINTAINERS: add reviewer for Spanish translations docs: ignore __counted_by attribute in structure definitions scripts: kernel-doc: Clarify missing struct member description ..