riscv/qemu - qemu - Gitea: Git with a cup of tea

124870 Commits

68 Branches

448 Tags

581 MiB

Tree: e9d02b5931

Commit Graph

Author SHA1 Message Date

Author	SHA1	Message	Date
Peter Maydell	9cbe72b868	scripts/kernel-doc: tweak for QEMU coding standards This commit makes the equivalent changes to the Python script that we had for the old Perl script in commit `4cf4179441` ("docs: tweak kernel-doc for QEMU coding standards"). To repeat the rationale from that commit: Surprisingly, QEMU does have a pretty consistent doc comment style and it is not very different from the Linux kernel's. Of the documentation "sigils", only "#" separates the QEMU doc comment style from Linux's, and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in accel/tcg/translate-all.c), so it's clear that the two standards are different in this respect. In addition, our structs are typedefed and recognized by CamelCase names. Note that in `4cf4179441` we used '(?!)' as our type_fallback regex; this is strictly not quite a replacement for the upstream '\&([_\w]+)', because the latter includes a group that can later be matched with \1, and the former does not. The old perl script did not care about this, but the python version does, so we must include the extra set of brackets to ensure we have a group. This commit does not include all the same changes that `4cf4179441` did. Of the missing pieces, some had already gone in an earlier kernel-doc update; the parts we still had but do not include here are: @@ -2057,7 +2060,7 @@ } elsif (/$doc_decl/o) { $identifier = $1; - if (/\s([\w\s]+?)(\(\))?\s-/) { + if (/\s([\w\s]+?)(\s-\|:)/) { $identifier = $1; } @@ -2067,7 +2070,7 @@ $contents = ""; $section = $section_default; $new_start_line = $. + 1; - if (/-(.)/) { + if (/[-:](.)/) { # strip leading/trailing/multiple spaces $descr= $1; $descr =~ s/^\s//; The second of these is already in the upstream version: the line r = KernRe("[-:](.)") in process_name() matches the regex we have. The first change has been refactored into the doc_begin_data and doc_begin_func changes. Since the output HTML for QEMU's documentation has no relevant changes with the new kerneldoc, we assume that this too has been handled upstream. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-id: 20250814171324.1614516-6-peter.maydell@linaro.org	8 months ago
Peter Maydell	2b2765ac40	scripts: Import Python kerneldoc from Linux kernel We last synced our copy of kerneldoc with Linux back in 2020. In the interim, upstream has entirely rewritten the script in Python, and the new Python version is split into a main script plus some libraries in the kernel's scripts/lib/kdoc. Import all these files. These are the versions as of kernel commit 0cc53520e68be, with no local changes. We use the same lib/kdoc/ directory as the kernel does here, so we can avoid having to edit the top-level script just to adjust a pathname, even though it is probably not the naming we would have picked if this was a purely QEMU script. The Sphinx conf.py still points at the Perl version of the script, so this Python code will not be invoked to build the docs yet. NB: checkpatch complains about many things in this commit, including the use of "GPL-2.0" rather than "GPL-2.0-only" in the SPDX tags, but since this is a third party import we can ignore this. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-id: 20250814171324.1614516-4-peter.maydell@linaro.org	8 months ago

Peter Maydell

9cbe72b868

scripts/kernel-doc: tweak for QEMU coding standards

This commit makes the equivalent changes to the Python script that we
had for the old Perl script in commit 4cf4179441 ("docs: tweak
kernel-doc for QEMU coding standards").  To repeat the rationale from
that commit:

    Surprisingly, QEMU does have a pretty consistent doc comment style and
    it is not very different from the Linux kernel's.  Of the documentation
    "sigils", only "#" separates the QEMU doc comment style from Linux's,
    and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in
    accel/tcg/translate-all.c), so it's clear that the two standards are
    different in this respect.  In addition, our structs are typedefed and
    recognized by CamelCase names.

Note that in 4cf4179441 we used '(?!)' as our type_fallback regex;
this is strictly not quite a replacement for the upstream
'\&([_\w]+)', because the latter includes a group that can later be
matched with \1, and the former does not.  The old perl script did
not care about this, but the python version does, so we must include
the extra set of brackets to ensure we have a group.

This commit does not include all the same changes that 4cf4179441
did.  Of the missing pieces, some had already gone in an earlier
kernel-doc update; the parts we still had but do not include here are:

    @@ -2057,7 +2060,7 @@
         }
         elsif (/$doc_decl/o) {
            $identifier = $1;
    -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
    +       if (/\s*([\w\s]+?)(\s*-|:)/) {
                $identifier = $1;
            }

    @@ -2067,7 +2070,7 @@
            $contents = "";
            $section = $section_default;
            $new_start_line = $. + 1;
    -       if (/-(.*)/) {
    +       if (/[-:](.*)/) {
                # strip leading/trailing/multiple spaces
                $descr= $1;
                $descr =~ s/^\s*//;

The second of these is already in the upstream version: the line r =
KernRe("[-:](.*)") in process_name() matches the regex we have.  The
first change has been refactored into the doc_begin_data and
doc_begin_func changes.  Since the output HTML for QEMU's
documentation has no relevant changes with the new kerneldoc, we
assume that this too has been handled upstream.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-id: 20250814171324.1614516-6-peter.maydell@linaro.org

8 months ago

Peter Maydell

2b2765ac40

scripts: Import Python kerneldoc from Linux kernel

We last synced our copy of kerneldoc with Linux back in 2020.  In the
interim, upstream has entirely rewritten the script in Python, and
the new Python version is split into a main script plus some
libraries in the kernel's scripts/lib/kdoc.

Import all these files.  These are the versions as of kernel commit
0cc53520e68be, with no local changes.

We use the same lib/kdoc/ directory as the kernel does here, so we
can avoid having to edit the top-level script just to adjust a
pathname, even though it is probably not the naming we would have
picked if this was a purely QEMU script.

The Sphinx conf.py still points at the Perl version of the script,
so this Python code will not be invoked to build the docs yet.

NB: checkpatch complains about many things in this commit,
including the use of "GPL-2.0" rather than "GPL-2.0-only" in
the SPDX tags, but since this is a third party import we can
ignore this.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-id: 20250814171324.1614516-4-peter.maydell@linaro.org

8 months ago

2 Commits (e9d02b59316fcbc9650d747b06e2755374ab3b70)