From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> To: Jonathan Corbet <corbet@lwn.net> Cc: Christoph Hellwig <hch@infradead.org>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Ingo Molnar <mingo@redhat.com>, Peter Zijlstra <peterz@infradead.org> Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Date: Thu, 10 May 2018 11:21:13 -0300 [thread overview] Message-ID: <20180510112113.4db65764@vento.lan> (raw) In-Reply-To: <20180510073012.5902088e@lwn.net> Em Thu, 10 May 2018 07:30:12 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Thu, 10 May 2018 06:38:05 -0300 > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > > > (Peter said): > > > Independent of any philosophical discussion not allowing a setence to > > > end with a single ':' is completely idiotic. Please fix the tooling > > > instead to allow it, as it is very important for being able to just > > > write understandable comments. > > FWIW, there's no problem with a sentence ending with a single colon. > It's only an issue if you want to flag a special interpretation for the > text that follows that sentence. Just to be precise. > > > Patches are welcome, although I don't see any easy way to solve it. > > I could envision some sort of heuristic that would recognize an indented > block containing code. Probably we could go simpler and force the > "literal block" treatment for any indented block that lacks explicit > enumeration markers. So: > > this->would_be("a literal block"); > > but: > > - This would not be > > Such a thing would likely be a bit fragile (people feel, rightly, that > they can put anything into normal text) but it might just work well > enough. For best results, it should probably be done as part of Sphinx > itself, rather than yet another ugly hack in the kerneldoc script. I guess that it also won't work... $ git grep -A2 "\*\s.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d : -f 4-) Present some matches that seem to be violating such hint. drivers/edac/edac_device.h:/* The offset value can be: drivers/edac/edac_device.h- * -1 indicating no offset value drivers/edac/edac_device.h- * 0 for zero-based block numbers drivers/gpu/drm/drm_scdc_helper.c: * As per the spec: drivers/gpu/drm/drm_scdc_helper.c- * TMDS clock rate for pixel clock < 340 MHz = 1x the character drivers/gpu/drm/drm_scdc_helper.c- * rate = 1/10 pixel clock rate I didn't actually check if those are part of a Kernel-doc markup, though, but it shows that people sometimes don't add a "prepend" character to a list. In the specific case of errors, prepending with a "-" can be weird, as it may lead ugly things like: * - -1 indicating no offset value * - 0 for zero-based block numbers The problem with a hint-based mechanism is that it will generate false hints. If added, we may end by needing to add extra tags to disable the hints mechanism where it gets wrong, or to periodically do code changes at kernel-doc comments in order to make the hints logic happy. So, IMO, we should provide non-hints based mechanism, like forcing the string that prepends the colon to have a keyword that will make it to parse the block as literal, where expressions like: See the code-block foo: See the following code example: See the following flow diagram: See the following artwork: Is the best alternative to avoid "::", as on the enclosed patch. > This particular problem may be solvable, and I'll look into it, but not > right away. The offline world is being rather insistently obnoxious > these days... Thanks, Mauro [PATCH] Mark a diagram at wait.h as such, using a code-block for it Instead of explicitly using "::" to mark the diagram, detect it based on code words inside the description. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> diff --git a/include/linux/wait.h b/include/linux/wait.h index d9f131ecf708..c360c5947374 100644 --- a/include/linux/wait.h +++ b/include/linux/wait.h @@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry *wq_entry, wait_queue_func_t f * lead to sporadic and non-obvious failure. * * Use either while holding wait_queue_head::lock or when used for wakeups - * with an extra smp_mb() like: + * with an extra smp_mb() like on this diagram: * * CPU0 - waker CPU1 - waiter * diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0057d8eafcc1..1c69072997f8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -803,7 +803,12 @@ sub output_highlight_rst { # if (! $in_literal) { $block .= $line . "\n"; - if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { + if ($block =~ s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) { + $in_literal = 1; + $litprefix = ""; + $output .= highlight_block($block); + $block = "" + } elsif (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { $in_literal = 1; $litprefix = ""; $output .= highlight_block($block);
WARNING: multiple messages have this Message-ID (diff)
From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> To: Jonathan Corbet <corbet@lwn.net> Cc: Christoph Hellwig <hch@infradead.org>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Ingo Molnar <mingo@redhat.com>, Peter Zijlstra <peterz@infradead.org> Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Date: Thu, 10 May 2018 11:21:13 -0300 [thread overview] Message-ID: <20180510112113.4db65764@vento.lan> (raw) In-Reply-To: <20180510073012.5902088e@lwn.net> Em Thu, 10 May 2018 07:30:12 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Thu, 10 May 2018 06:38:05 -0300 > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > > > (Peter said): > > > Independent of any philosophical discussion not allowing a setence to > > > end with a single ':' is completely idiotic. Please fix the tooling > > > instead to allow it, as it is very important for being able to just > > > write understandable comments. > > FWIW, there's no problem with a sentence ending with a single colon. > It's only an issue if you want to flag a special interpretation for the > text that follows that sentence. Just to be precise. > > > Patches are welcome, although I don't see any easy way to solve it. > > I could envision some sort of heuristic that would recognize an indented > block containing code. Probably we could go simpler and force the > "literal block" treatment for any indented block that lacks explicit > enumeration markers. So: > > this->would_be("a literal block"); > > but: > > - This would not be > > Such a thing would likely be a bit fragile (people feel, rightly, that > they can put anything into normal text) but it might just work well > enough. For best results, it should probably be done as part of Sphinx > itself, rather than yet another ugly hack in the kerneldoc script. I guess that it also won't work... $ git grep -A2 "\*\s.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d : -f 4-) Present some matches that seem to be violating such hint. drivers/edac/edac_device.h:/* The offset value can be: drivers/edac/edac_device.h- * -1 indicating no offset value drivers/edac/edac_device.h- * 0 for zero-based block numbers drivers/gpu/drm/drm_scdc_helper.c: * As per the spec: drivers/gpu/drm/drm_scdc_helper.c- * TMDS clock rate for pixel clock < 340 MHz = 1x the character drivers/gpu/drm/drm_scdc_helper.c- * rate = 1/10 pixel clock rate I didn't actually check if those are part of a Kernel-doc markup, though, but it shows that people sometimes don't add a "prepend" character to a list. In the specific case of errors, prepending with a "-" can be weird, as it may lead ugly things like: * - -1 indicating no offset value * - 0 for zero-based block numbers The problem with a hint-based mechanism is that it will generate false hints. If added, we may end by needing to add extra tags to disable the hints mechanism where it gets wrong, or to periodically do code changes at kernel-doc comments in order to make the hints logic happy. So, IMO, we should provide non-hints based mechanism, like forcing the string that prepends the colon to have a keyword that will make it to parse the block as literal, where expressions like: See the code-block foo: See the following code example: See the following flow diagram: See the following artwork: Is the best alternative to avoid "::", as on the enclosed patch. > This particular problem may be solvable, and I'll look into it, but not > right away. The offline world is being rather insistently obnoxious > these days... Thanks, Mauro [PATCH] Mark a diagram at wait.h as such, using a code-block for it Instead of explicitly using "::" to mark the diagram, detect it based on code words inside the description. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> diff --git a/include/linux/wait.h b/include/linux/wait.h index d9f131ecf708..c360c5947374 100644 --- a/include/linux/wait.h +++ b/include/linux/wait.h @@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry *wq_entry, wait_queue_func_t f * lead to sporadic and non-obvious failure. * * Use either while holding wait_queue_head::lock or when used for wakeups - * with an extra smp_mb() like: + * with an extra smp_mb() like on this diagram: * * CPU0 - waker CPU1 - waiter * diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0057d8eafcc1..1c69072997f8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -803,7 +803,12 @@ sub output_highlight_rst { # if (! $in_literal) { $block .= $line . "\n"; - if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { + if ($block =~ s/(code|example|artwork|flow|diagram)([^\:]*:)\n/$1$2:\n/) { + $in_literal = 1; + $litprefix = ""; + $output .= highlight_block($block); + $block = "" + } elsif (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { $in_literal = 1; $litprefix = ""; $output .= highlight_block($block); -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
next prev parent reply other threads:[~2018-05-10 14:21 UTC|newest] Thread overview: 184+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-05-07 9:35 [PATCH 00/18] Fix some build warnings/errors with Sphinx Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 01/18] docs: can.rst: fix a footnote reference Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 18:41 ` Oliver Hartkopp 2018-05-07 18:41 ` Oliver Hartkopp 2018-05-07 9:35 ` [PATCH 02/18] docs: fix location of request_firmware & friends Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 15:49 ` Luis R. Rodriguez 2018-05-08 15:49 ` Luis R. Rodriguez 2018-05-09 12:26 ` Mauro Carvalho Chehab 2018-05-09 12:26 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 15:59 ` Jonathan Corbet 2018-05-08 15:59 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 04/18] docs: admin-guide: add bcache documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 16:01 ` Jonathan Corbet 2018-05-08 16:01 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 05/18] docs: core-api: add cachetlb documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:29 ` Andrea Parri 2018-05-07 12:29 ` Andrea Parri 2018-05-08 14:40 ` Jani Nikula 2018-05-08 14:40 ` Jani Nikula 2018-05-08 16:02 ` Andrea Parri 2018-05-08 16:02 ` Andrea Parri 2018-05-08 16:28 ` Andrea Parri 2018-05-08 16:28 ` Andrea Parri 2018-05-08 18:05 ` Mauro Carvalho Chehab 2018-05-08 18:05 ` Mauro Carvalho Chehab 2018-05-08 18:28 ` Mauro Carvalho Chehab 2018-05-08 18:28 ` Mauro Carvalho Chehab 2018-05-08 19:05 ` Andrea Parri 2018-05-08 19:05 ` Andrea Parri 2018-05-08 16:04 ` Jonathan Corbet 2018-05-08 16:04 ` Jonathan Corbet 2018-05-08 16:51 ` Andrea Parri 2018-05-08 16:51 ` Andrea Parri 2018-05-07 9:35 ` [PATCH 06/18] docs: core-api: add cgroup-v2 documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 15:51 ` Jonathan Corbet 2018-05-08 15:51 ` Jonathan Corbet 2018-05-09 12:02 ` Mauro Carvalho Chehab 2018-05-09 12:02 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 07/18] docs: core-api: add circular-buffers documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:31 ` Andrea Parri 2018-05-07 12:31 ` Andrea Parri 2018-05-08 16:08 ` Jonathan Corbet 2018-05-08 16:08 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 08/18] docs: driver-api: add clk documentation Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 16:10 ` Jonathan Corbet 2018-05-08 16:10 ` Jonathan Corbet 2018-05-07 9:35 ` [PATCH 09/18] net: mac80211.h: fix a bad comment line Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 12:37 ` Kalle Valo 2018-05-07 12:37 ` Kalle Valo 2018-05-07 12:38 ` Johannes Berg 2018-05-07 12:38 ` Johannes Berg 2018-05-09 12:04 ` Mauro Carvalho Chehab 2018-05-09 12:04 ` Mauro Carvalho Chehab 2018-05-09 12:04 ` Johannes Berg 2018-05-09 12:04 ` Johannes Berg 2018-05-07 9:35 ` [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff() Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 14:23 ` Paul E. McKenney 2018-05-07 14:23 ` Paul E. McKenney 2018-05-09 11:55 ` Mauro Carvalho Chehab 2018-05-09 11:55 ` Mauro Carvalho Chehab 2018-05-14 19:40 ` Paul E. McKenney 2018-05-14 19:40 ` Paul E. McKenney 2018-05-07 9:35 ` [PATCH 11/18] docs: crypto_engine.rst: Fix two parse warnings Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 12/18] time: timer.c: adjust a kernel-doc comment Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-13 14:00 ` [tip:timers/core] timers: Adjust " tip-bot for Mauro Carvalho Chehab 2018-05-13 14:00 ` tip-bot for Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-09 8:41 ` Peter Zijlstra 2018-05-09 8:41 ` Peter Zijlstra 2018-05-09 14:45 ` Jonathan Corbet 2018-05-09 14:45 ` Jonathan Corbet 2018-05-09 15:20 ` Peter Zijlstra 2018-05-09 15:20 ` Peter Zijlstra 2018-05-09 18:35 ` Jonathan Corbet 2018-05-09 18:35 ` Jonathan Corbet 2018-05-09 18:50 ` Markus Heiser 2018-05-09 18:50 ` Markus Heiser 2018-05-09 19:31 ` Peter Zijlstra 2018-05-09 19:31 ` Peter Zijlstra 2018-05-10 12:23 ` Andrea Parri 2018-05-10 12:23 ` Andrea Parri 2018-05-10 13:15 ` Jonathan Corbet 2018-05-10 13:15 ` Jonathan Corbet 2018-05-10 16:52 ` Andrea Parri 2018-05-10 16:52 ` Andrea Parri 2018-05-10 17:45 ` Mauro Carvalho Chehab 2018-05-10 17:45 ` Mauro Carvalho Chehab 2018-05-10 8:38 ` Christoph Hellwig 2018-05-10 8:38 ` Christoph Hellwig 2018-05-10 9:38 ` Mauro Carvalho Chehab 2018-05-10 9:38 ` Mauro Carvalho Chehab 2018-05-10 12:20 ` Peter Zijlstra 2018-05-10 12:20 ` Peter Zijlstra 2018-05-10 13:04 ` Mauro Carvalho Chehab 2018-05-10 13:04 ` Mauro Carvalho Chehab 2018-05-10 13:30 ` Jonathan Corbet 2018-05-10 13:30 ` Jonathan Corbet 2018-05-10 13:31 ` Jonathan Corbet 2018-05-10 13:31 ` Jonathan Corbet 2018-05-10 14:21 ` Mauro Carvalho Chehab [this message] 2018-05-10 14:21 ` Mauro Carvalho Chehab 2018-05-10 15:38 ` Jonathan Corbet 2018-05-10 15:38 ` Jonathan Corbet 2018-05-10 16:42 ` Mauro Carvalho Chehab 2018-05-10 16:42 ` Mauro Carvalho Chehab 2018-05-10 17:14 ` Mauro Carvalho Chehab 2018-05-10 17:14 ` Mauro Carvalho Chehab 2018-05-11 7:06 ` Markus Heiser 2018-05-11 7:06 ` Markus Heiser 2018-05-07 9:35 ` [PATCH 14/18] fbdev: modedb.c: fix a kernel-doc markup Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-15 10:22 ` Bartlomiej Zolnierkiewicz 2018-05-07 9:35 ` [PATCH 15/18] iio: iio.h: use nested struct support on " Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 17:08 ` Jonathan Cameron 2018-05-07 17:08 ` Jonathan Cameron 2018-05-09 12:00 ` Mauro Carvalho Chehab 2018-05-09 12:00 ` Mauro Carvalho Chehab 2018-05-07 9:35 ` [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-07 9:46 ` Boris Brezillon 2018-05-07 9:46 ` Boris Brezillon 2018-05-07 11:32 ` Mauro Carvalho Chehab 2018-05-07 11:32 ` Mauro Carvalho Chehab 2018-05-09 12:02 ` Boris Brezillon 2018-05-09 12:02 ` Boris Brezillon 2018-05-09 12:10 ` Mauro Carvalho Chehab 2018-05-09 12:10 ` Mauro Carvalho Chehab 2018-05-09 12:22 ` Boris Brezillon 2018-05-09 12:22 ` Boris Brezillon 2018-05-09 13:28 ` Mauro Carvalho Chehab 2018-05-09 13:28 ` Mauro Carvalho Chehab 2018-05-09 15:56 ` Boris Brezillon 2018-05-09 15:56 ` Boris Brezillon 2018-05-07 9:35 ` [PATCH 17/18] docs: uio-howto.rst: use a code block to solve a warning Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-08 3:07 ` Greg Kroah-Hartman 2018-05-07 9:35 ` [PATCH 18/18] w1: w1_io.c: fix a kernel-doc warning Mauro Carvalho Chehab 2018-05-07 9:35 ` Mauro Carvalho Chehab 2018-05-08 11:03 ` Evgeniy Polyakov 2018-05-08 11:03 ` Evgeniy Polyakov 2018-05-09 12:32 ` Mauro Carvalho Chehab 2018-05-09 12:32 ` Mauro Carvalho Chehab 2018-05-09 13:11 ` Jonathan Corbet 2018-05-09 13:11 ` Jonathan Corbet 2018-05-10 10:37 ` Evgeniy Polyakov 2018-05-10 10:37 ` Evgeniy Polyakov 2018-05-08 16:13 ` [PATCH 00/18] Fix some build warnings/errors with Sphinx Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 16:13 ` Jonathan Corbet 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez 2018-05-08 17:36 ` Luis R. Rodriguez
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=20180510112113.4db65764@vento.lan \ --to=mchehab+samsung@kernel.org \ --cc=corbet@lwn.net \ --cc=hch@infradead.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=mchehab@infradead.org \ --cc=mingo@redhat.com \ --cc=peterz@infradead.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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.