qemu/scripts/kernel-doc, branch master

scripts/kernel-doc: strip QEMU_ from function definitions

2021-03-24T14:24:40Z

Some packaged versions of Sphinx (fedora33/alpine so far) have issues with the annotated C code that kernel-doc spits out. Without knowing about things like QEMU_PLUGIN_EXPORT it chokes trying to understand the code. Evidently this is a problem for the kernel as well as the long stream of regex substitutions we add to in this patch can attest. Fortunately we have a fairly common format for all our compiler shenanigans as applied to functions so lets just filter them all out. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Message-Id: <20210323165308.15244-2-alex.bennee@linaro.org>

scripts: kernel-doc: remove unnecessary change wrt Linux

2020-12-10T17:15:25Z

A comment in kernel-doc mentions QEMU's qatomic_set macro, but since this code originated in Linux we should just revert it and stay as close to the kernel's copy of the script as possible. The change was introduced (more or less unintentionally) in QEMU commit commit d73415a31547, which did a global search-and-replace of QEMU's atomic access macros. Suggested-by: Peter Maydell Signed-off-by: Paolo Bonzini

scripts: kernel-doc: use :c:union when needed

2020-12-10T17:15:25Z

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 Link: https://lore.kernel.org/r/6e4ec3eec914df62389a299797a3880ae4490f35.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-30-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

scripts: kernel-doc: split typedef complex regex

2020-12-10T17:15:24Z

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 Link: https://lore.kernel.org/r/3a4af999a0d62d4ab9dfae1cdefdfcad93383356.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-29-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

scripts: kernel-doc: fix typedef parsing

2020-12-10T17:15:24Z

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 Link: https://lore.kernel.org/r/328e8018041cc44f7a1684e57f8d111230761c4f.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-28-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

Revert "kernel-doc: Handle function typedefs that return pointers"

2020-12-10T17:15:24Z

This reverts commit 19ab6044be0c55d529e875e3ee16fdd5c3b54d33. We will replace the commit with the fix from Linux. Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-27-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

Revert "kernel-doc: Handle function typedefs without asterisks"

2020-12-10T17:15:24Z

This reverts commit 3cd3c5193cde5242e243c25759f85802e267994f. We will replace the commit with the fix from Linux. Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-26-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

scripts: kernel-doc: try to use c:function if possible

2020-12-10T17:15:24Z

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 Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-25-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

scripts: kernel-doc: fix line number handling

2020-12-10T17:15:24Z

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 Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-24-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini

scripts: kernel-doc: allow passing desired Sphinx C domain dialect

2020-12-10T17:15:23Z

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 argument. Thanks-to: Joe Perches Suggested-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-23-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini