From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org
Subject: [PATCH v5 50/52] scripts: kernel-doc: try to use c:function if possible
Date: Tue, 6 Oct 2020 16:03:47 +0200 [thread overview]
Message-ID: <62b87762d9747e9aa5064f70dd216858c721ba41.1601992016.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1601992016.git.mchehab+huawei@kernel.org>
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>
---
scripts/kernel-doc | 23 ++++++++++++++---------
1 file changed, 14 insertions(+), 9 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9881f08cf75c..a3453de4495c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -913,6 +913,7 @@ sub output_function_rst(%) {
my ($parameter, $section);
my $oldprefix = $lineprefix;
my $start = "";
+ my $is_macro = 0;
if ($sphinx_major < 3) {
if ($args{'typedef'}) {
@@ -922,11 +923,17 @@ sub output_function_rst(%) {
$lineprefix = "";
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
+ $is_macro = 1;
} else {
print ".. c:function:: ";
}
} else {
- print ".. c:macro:: ". $args{'function'} . "\n\n";
+ if ($args{'typedef'} || $args{'functiontype'} eq "") {
+ $is_macro = 1;
+ print ".. c:macro:: ". $args{'function'} . "\n\n";
+ } else {
+ print ".. c:function:: ";
+ }
if ($args{'typedef'}) {
print_lineno($declaration_start_line);
@@ -935,7 +942,7 @@ sub output_function_rst(%) {
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
- print "``";
+ print "``" if ($is_macro);
}
}
if ($args{'functiontype'} ne "") {
@@ -960,14 +967,12 @@ sub output_function_rst(%) {
print $type;
}
}
- if ($args{'typedef'}) {
- print ");``\n\n";
+ if ($is_macro) {
+ print ")``\n\n";
} else {
- if ($sphinx_major < 3) {
- print ")\n\n";
- } else {
- print ")``\n";
- }
+ print ")\n\n";
+ }
+ if (!$args{'typedef'}) {
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.26.2
next prev parent reply other threads:[~2020-10-06 14:05 UTC|newest]
Thread overview: 61+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-06 14:02 [PATCH v5 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-10-06 14:02 ` [PATCH v5 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
2020-10-06 14:02 ` [PATCH v5 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 06/52] scripts: kernel-doc: fix troubles with line counts Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 07/52] scripts: kernel-doc: reimplement -nofunction argument Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 08/52] scripts: kernel-doc: fix typedef identification Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 09/52] scripts: kernel-doc: don't mangle with parameter list Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 10/52] scripts: kernel-doc: allow passing desired Sphinx C domain dialect Mauro Carvalho Chehab
2020-10-06 21:18 ` kernel test robot
2020-10-12 12:33 ` [PATCH v5.1 " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 11/52] docs: kerneldoc.py: append the name of the parsed doc file Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 12/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 13/52] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 14/52] media: docs: make V4L documents more " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 15/52] media: docs: make DVB " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 16/52] media: docs: make MC " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 17/52] media: docs: make RC " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 18/52] media: cec-core.rst: don't use c:type for structs Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 19/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 20/52] memblock: get rid of a :c:type leftover Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 21/52] docs: remove some replace macros like |struct foo| Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 22/52] docs: get rid of :c:type explicit declarations for structs Mauro Carvalho Chehab
2020-10-06 16:41 ` Greg Kroah-Hartman
2020-10-06 14:03 ` [PATCH v5 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
2020-10-06 14:13 ` Stefan Schmidt
2020-10-06 14:14 ` Stefan Schmidt
2020-10-06 14:03 ` [PATCH v5 26/52] docs: genericirq.rst: don't document chip.c functions twice Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 28/52] docs: remove sound API duplication Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 32/52] docs: basics.rst: get rid of rcu kernel-doc macros Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
2020-10-06 19:19 ` Eric Biggers
2020-10-14 7:12 ` Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 36/52] docs: devices.rst: get rid of :c:type macros Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 38/52] docs: block: blk-mq.rst: " Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 40/52] docs: fpga: replace :c:member: macros Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 43/52] docs: infrastructure.rst: don't include firmware kernel-doc Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 44/52] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 45/52] docs: devices.rst: fix a C reference markup Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 48/52] docs: basics.rst: avoid duplicated C function declaration Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
2020-10-06 14:03 ` Mauro Carvalho Chehab [this message]
2020-10-06 14:03 ` [PATCH v5 51/52] docs: conf.py: fix c:function support with Sphinx 3.x Mauro Carvalho Chehab
2020-10-06 14:03 ` [PATCH v5 52/52] docs: conf.py: change the Sphinx 3.x+ text Mauro Carvalho Chehab
2020-10-06 16:56 ` [PATCH v5 00/52] Fix html build with Sphinx 3.1 and above Joe Perches
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=62b87762d9747e9aa5064f70dd216858c721ba41.1601992016.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).