* excess bolding in html
@ 2020-10-30 3:17 Randy Dunlap
2020-10-30 7:37 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 8+ messages in thread
From: Randy Dunlap @ 2020-10-30 3:17 UTC (permalink / raw)
To: linux-doc, Jonathan Corbet, Mauro Carvalho Chehab
Hi,
I have noticed a few cases of excess bolding in generated html (seen in both
Firefox and Opera web browsers).
(1) https://www.kernel.org/doc/html/latest/kernel-hacking/locking.html#futex-api-reference
In the description of struct hrtimer_sleeper * futex_setup_timer:
Both the Return line and the next following line are all bold, while the third (final)
line is not bold (as expected):
Return
Initialized hrtimer_sleeper structure or NULL if no timeout
value given
(2) https://www.kernel.org/doc/html/latest/filesystems/api-summary.html
In the description of int seq_open():
Both the Note line and the following line are all bold, while the final line
is not bold (as expected):
Note
seq_open() will allocate a struct seq_file and store its
pointer in file->private_data. This pointer should not be modified.
I looked at scripts/kernel-doc briefly but did not see where this is
happening, so if anyone out there wants a small project to fix,
please go for it.
--
~Randy
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 3:17 excess bolding in html Randy Dunlap
@ 2020-10-30 7:37 ` Mauro Carvalho Chehab
2020-10-30 11:31 ` Matthew Wilcox
0 siblings, 1 reply; 8+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-30 7:37 UTC (permalink / raw)
To: Randy Dunlap; +Cc: linux-doc, Jonathan Corbet
Hi Randy,
Em Thu, 29 Oct 2020 20:17:34 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:
> Hi,
>
> I have noticed a few cases of excess bolding in generated html (seen in both
> Firefox and Opera web browsers).
>
> (1) https://www.kernel.org/doc/html/latest/kernel-hacking/locking.html#futex-api-reference
>
> In the description of struct hrtimer_sleeper * futex_setup_timer:
>
> Both the Return line and the next following line are all bold, while the third (final)
> line is not bold (as expected):
>
> Return
>
> Initialized hrtimer_sleeper structure or NULL if no timeout
> value given
The problem is related to the indentation of "value given".
With ReST, this causes the first line to be print in bold.
The reason for that is that a common practice to describe
arguments on texts is to use this:
foo
Does foo things
bar
Does bar things
Without this feature at ReST, the above would need to be:
**foo**
Does foo things
**bar**
Does bar things
Which is more polluted with symbols, on text mode.
-
Just changing the kernel-doc markup at kernel/futex.c:
/**
* futex_setup_timer - set up the sleeping hrtimer.
* @time: ptr to the given timeout value
* @timeout: the hrtimer_sleeper structure to be set up
* @flags: futex flags
* @range_ns: optional range in ns
*
* Return: Initialized hrtimer_sleeper structure or NULL if no timeout
* value given
*/
To:
...
* Return:
*
* Initialized hrtimer_sleeper structure or NULL if no timeout
* value given
*/
Should fix it.
>
> (2) https://www.kernel.org/doc/html/latest/filesystems/api-summary.html
>
> In the description of int seq_open():
>
> Both the Note line and the following line are all bold, while the final line
> is not bold (as expected):
>
> Note
>
> seq_open() will allocate a struct seq_file and store its
> pointer in file->private_data. This pointer should not be modified.
>
>
>
> I looked at scripts/kernel-doc briefly but did not see where this is
> happening, so if anyone out there wants a small project to fix,
> please go for it.
We can't make kernel-doc ignore alignments, as otherwise other
things will break, as several kernel-doc markups use indents
for some things (like supporting literal-blocks).
So, such kind of fixes need to be done at the kernel-doc markups.
In this very specific case, though, I guess, some regex could
be used to convert things like:
* Foo: some multiline
* description
into something like:
* Foo:
*
* some multiline
* description
or:
* Foo:
*
* some multiline
* description
kernel-doc uses this regex to match "Return":
my $doc_sect = $doc_com .
'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
I guess something could be added after this:
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
in order do to the replacement. Maybe something like this (untested):
if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
my $spaces = $newsection;
$spaces =~ s/\S/ /;
$newcontents = $spaces . $newcontents;
Would do the trick.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 7:37 ` Mauro Carvalho Chehab
@ 2020-10-30 11:31 ` Matthew Wilcox
2020-10-30 12:28 ` Markus Heiser
0 siblings, 1 reply; 8+ messages in thread
From: Matthew Wilcox @ 2020-10-30 11:31 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Randy Dunlap, linux-doc, Jonathan Corbet
On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
> Just changing the kernel-doc markup at kernel/futex.c:
>
> /**
> * futex_setup_timer - set up the sleeping hrtimer.
> * @time: ptr to the given timeout value
> * @timeout: the hrtimer_sleeper structure to be set up
> * @flags: futex flags
> * @range_ns: optional range in ns
> *
> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> * value given
> */
>
> To:
>
> ...
> * Return:
> *
> * Initialized hrtimer_sleeper structure or NULL if no timeout
> * value given
> */
>
> Should fix it.
Or just remove the indent.
* Return: Initialized hrtimer_sleeper structure or NULL if no timeout
* value given.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 11:31 ` Matthew Wilcox
@ 2020-10-30 12:28 ` Markus Heiser
2020-10-30 12:53 ` Matthew Wilcox
0 siblings, 1 reply; 8+ messages in thread
From: Markus Heiser @ 2020-10-30 12:28 UTC (permalink / raw)
To: Matthew Wilcox, Mauro Carvalho Chehab
Cc: Randy Dunlap, linux-doc, Jonathan Corbet
Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
> On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
>> Just changing the kernel-doc markup at kernel/futex.c:
>>
>> /**
>> * futex_setup_timer - set up the sleeping hrtimer.
>> * @time: ptr to the given timeout value
>> * @timeout: the hrtimer_sleeper structure to be set up
>> * @flags: futex flags
>> * @range_ns: optional range in ns
>> *
>> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>> * value given
>> */
>>
>> To:
>>
>> ...
>> * Return:
>> *
>> * Initialized hrtimer_sleeper structure or NULL if no timeout
>> * value given
>> */
>>
>> Should fix it.
>
> Or just remove the indent.
>
> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> * value given.
To add my 2 cent:
The return value should be described in a dedicated section
named "Return:", like shown im Mauro's example (compare [1]).
For on-liners I think it is OK to use the short form (compare [2]).
[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
[2]
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation
-- Markus --
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 12:28 ` Markus Heiser
@ 2020-10-30 12:53 ` Matthew Wilcox
2020-10-30 14:00 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 8+ messages in thread
From: Matthew Wilcox @ 2020-10-30 12:53 UTC (permalink / raw)
To: Markus Heiser
Cc: Mauro Carvalho Chehab, Randy Dunlap, linux-doc, Jonathan Corbet
On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
> Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
> > On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
> > > Just changing the kernel-doc markup at kernel/futex.c:
> > >
> > > /**
> > > * futex_setup_timer - set up the sleeping hrtimer.
> > > * @time: ptr to the given timeout value
> > > * @timeout: the hrtimer_sleeper structure to be set up
> > > * @flags: futex flags
> > > * @range_ns: optional range in ns
> > > *
> > > * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > > * value given
> > > */
> > >
> > > To:
> > >
> > > ...
> > > * Return:
> > > *
> > > * Initialized hrtimer_sleeper structure or NULL if no timeout
> > > * value given
> > > */
> > >
> > > Should fix it.
> >
> > Or just remove the indent.
> >
> > * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > * value given.
>
> To add my 2 cent:
>
> The return value should be described in a dedicated section
> named "Return:", like shown im Mauro's example (compare [1]).
>
> For on-liners I think it is OK to use the short form (compare [2]).
>
> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation
Right. I'm saying that Mauro's suggestion is overly verbose and removing
the whitespace is the solution least likely to bring down the Wrath of
peterz.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 12:53 ` Matthew Wilcox
@ 2020-10-30 14:00 ` Mauro Carvalho Chehab
2020-10-30 14:19 ` [PATCH RFC] scripts: kernel-doc: better handle spaces after section markups Mauro Carvalho Chehab
2020-10-30 17:30 ` excess bolding in html Randy Dunlap
0 siblings, 2 replies; 8+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-30 14:00 UTC (permalink / raw)
To: Matthew Wilcox; +Cc: Markus Heiser, Randy Dunlap, linux-doc, Jonathan Corbet
Em Fri, 30 Oct 2020 12:53:13 +0000
Matthew Wilcox <willy@infradead.org> escreveu:
> On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
> > Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
> > > On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
> > > > Just changing the kernel-doc markup at kernel/futex.c:
> > > >
> > > > /**
> > > > * futex_setup_timer - set up the sleeping hrtimer.
> > > > * @time: ptr to the given timeout value
> > > > * @timeout: the hrtimer_sleeper structure to be set up
> > > > * @flags: futex flags
> > > > * @range_ns: optional range in ns
> > > > *
> > > > * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > > > * value given
> > > > */
> > > >
> > > > To:
> > > >
> > > > ...
> > > > * Return:
> > > > *
> > > > * Initialized hrtimer_sleeper structure or NULL if no timeout
> > > > * value given
> > > > */
> > > >
> > > > Should fix it.
> > >
> > > Or just remove the indent.
> > >
> > > * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > > * value given.
> >
> > To add my 2 cent:
> >
> > The return value should be described in a dedicated section
> > named "Return:", like shown im Mauro's example (compare [1]).
> >
> > For on-liners I think it is OK to use the short form (compare [2]).
> >
> > [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> > [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation
Yeah, I would use myself something like:
Return: foo
only for single-line returns, using:
Return:
foo
bar
for multi-line ones.
-
Anyway, I tried the enclosed patch. With that, it should now recognize
kernel-doc markups with:
* Return: Initialized hrtimer_sleeper structure or NULL if no timeout
* value given
And:
* Returns: 0 on success, -ENOSPC if no suitable hole is found, -EINTR if
* asked to wait for eviction and interrupted.
*/
(this example came from drivers/gpu/drm/i915/i915_gem_gtt.c)
I only did a fast check here, in order to verify if it won't be
producing additional warnings. I didn't check the html output.
Just the resulting ReST from kernel-doc and the "make htmldocs" warnings.
PS.: This handles only "Note(s)" and "Return(s)" sections.
Description and @var: are already handled using a different
logic elsewhere.
This could likely be generalized, but more work (and tests)
are required.
Thanks,
Mauro
[PATCH] scripts: kernel-doc: better handle spaces after section markups
Better handle things like:
* Return: foo
* description
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f699cf05d409..a91a2420cccf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names
my $doc_sect = $doc_com .
- '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+ '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -865,8 +865,21 @@ sub output_highlight_rst {
my $in_literal = 0;
my $litprefix;
my $block = "";
+ my $spaces = "";
+ my $first = 1;
foreach $line (split "\n",$input) {
+ if ($first) {
+ $spaces = $1 if ($line =~ (m/^(\s+)/));
+ $first = 0;
+ }
+
+ if ($spaces ne "") {
+ if (!($line =~ s/^$spaces//)) {
+ $spaces = "";
+ }
+ }
+
#
# If we're in a literal block, see if we should drop out
# of it. Otherwise pass the line straight through unmunged.
@@ -2135,8 +2148,9 @@ sub process_body($$) {
}
if (/$doc_sect/i) { # case insensitive for supported section names
+ my $spaces = "$1$2";
$newsection = $1;
- $newcontents = $2;
+ $newcontents = $3;
# map the supported section names to the canonical names
if ($newsection =~ m/^description$/i) {
@@ -2161,11 +2175,20 @@ sub process_body($$) {
$in_doc_sect = 1;
$state = STATE_BODY;
- $contents = $newcontents;
$new_start_line = $.;
- while (substr($contents, 0, 1) eq " ") {
- $contents = substr($contents, 1);
+
+ if ($newsection =~ m/(return|note)/i) {
+ $spaces =~ s/\S/ /g;
+ $newcontents = $spaces . $newcontents;
+ $newcontents =~ s/^\s+$//;
+ $contents = $newcontents;
+ } else {
+ $contents = $newcontents;
+ while (substr($newcontents, 0, 1) eq " ") {
+ $newcontents = substr($newcontents, 1);
+ }
}
+
if ($contents ne "") {
$contents .= "\n";
}
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH RFC] scripts: kernel-doc: better handle spaces after section markups
2020-10-30 14:00 ` Mauro Carvalho Chehab
@ 2020-10-30 14:19 ` Mauro Carvalho Chehab
2020-10-30 17:30 ` excess bolding in html Randy Dunlap
1 sibling, 0 replies; 8+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-30 14:19 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel, Randy Dunlap
Better handle things like:
* Return: foo
* description
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
I already posted this as part of a reply to Randy/Matthew.
As said there, I only did a fast check here, in order to verify if it
won't be producing additional warnings. I didn't check the html
output. Just the resulting ReST from kernel-doc and the
"make htmldocs" warnings.
Yet, let me post in separate, just in case someone has enough
time/bandwidth to test if this is working properly and it is not
causing regressions.
Feel free to either use, modify or drop it ;-)
scripts/kernel-doc | 33 ++++++++++++++++++++++++++++-----
1 file changed, 28 insertions(+), 5 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f699cf05d409..a91a2420cccf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names
my $doc_sect = $doc_com .
- '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+ '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -865,8 +865,21 @@ sub output_highlight_rst {
my $in_literal = 0;
my $litprefix;
my $block = "";
+ my $spaces = "";
+ my $first = 1;
foreach $line (split "\n",$input) {
+ if ($first) {
+ $spaces = $1 if ($line =~ (m/^(\s+)/));
+ $first = 0;
+ }
+
+ if ($spaces ne "") {
+ if (!($line =~ s/^$spaces//)) {
+ $spaces = "";
+ }
+ }
+
#
# If we're in a literal block, see if we should drop out
# of it. Otherwise pass the line straight through unmunged.
@@ -2135,8 +2148,9 @@ sub process_body($$) {
}
if (/$doc_sect/i) { # case insensitive for supported section names
+ my $spaces = "$1$2";
$newsection = $1;
- $newcontents = $2;
+ $newcontents = $3;
# map the supported section names to the canonical names
if ($newsection =~ m/^description$/i) {
@@ -2161,11 +2175,20 @@ sub process_body($$) {
$in_doc_sect = 1;
$state = STATE_BODY;
- $contents = $newcontents;
$new_start_line = $.;
- while (substr($contents, 0, 1) eq " ") {
- $contents = substr($contents, 1);
+
+ if ($newsection =~ m/(return|note)/i) {
+ $spaces =~ s/\S/ /g;
+ $newcontents = $spaces . $newcontents;
+ $newcontents =~ s/^\s+$//;
+ $contents = $newcontents;
+ } else {
+ $contents = $newcontents;
+ while (substr($newcontents, 0, 1) eq " ") {
+ $newcontents = substr($newcontents, 1);
+ }
}
+
if ($contents ne "") {
$contents .= "\n";
}
--
2.26.2
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: excess bolding in html
2020-10-30 14:00 ` Mauro Carvalho Chehab
2020-10-30 14:19 ` [PATCH RFC] scripts: kernel-doc: better handle spaces after section markups Mauro Carvalho Chehab
@ 2020-10-30 17:30 ` Randy Dunlap
1 sibling, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2020-10-30 17:30 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Matthew Wilcox
Cc: Markus Heiser, linux-doc, Jonathan Corbet
Hi Mauro,
Thanks for the patch.
On 10/30/20 7:00 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 30 Oct 2020 12:53:13 +0000
> Matthew Wilcox <willy@infradead.org> escreveu:
>
>> On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
>>> Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
>>>> On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
>>>>> Just changing the kernel-doc markup at kernel/futex.c:
>>>>>
>>>>> /**
>>>>> * futex_setup_timer - set up the sleeping hrtimer.
>>>>> * @time: ptr to the given timeout value
>>>>> * @timeout: the hrtimer_sleeper structure to be set up
>>>>> * @flags: futex flags
>>>>> * @range_ns: optional range in ns
>>>>> *
>>>>> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>>>>> * value given
>>>>> */
>>>>>
>>>>> To:
>>>>>
>>>>> ...
>>>>> * Return:
>>>>> *
>>>>> * Initialized hrtimer_sleeper structure or NULL if no timeout
>>>>> * value given
>>>>> */
>>>>>
>>>>> Should fix it.
>>>>
>>>> Or just remove the indent.
>>>>
>>>> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>>>> * value given.
>>>
>>> To add my 2 cent:
>>>
>>> The return value should be described in a dedicated section
>>> named "Return:", like shown im Mauro's example (compare [1]).
>>>
>>> For on-liners I think it is OK to use the short form (compare [2]).
>>>
>>> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
>>> [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation
>
> Yeah, I would use myself something like:
>
> Return: foo
>
> only for single-line returns, using:
>
> Return:
>
> foo
> bar
>
> for multi-line ones.
>
> -
>
> Anyway, I tried the enclosed patch. With that, it should now recognize
> kernel-doc markups with:
>
> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> * value given
>
> And:
>
> * Returns: 0 on success, -ENOSPC if no suitable hole is found, -EINTR if
> * asked to wait for eviction and interrupted.
> */
> (this example came from drivers/gpu/drm/i915/i915_gem_gtt.c)
>
> I only did a fast check here, in order to verify if it won't be
> producing additional warnings. I didn't check the html output.
> Just the resulting ReST from kernel-doc and the "make htmldocs" warnings.
>
> PS.: This handles only "Note(s)" and "Return(s)" sections.
> Description and @var: are already handled using a different
> logic elsewhere.
>
> This could likely be generalized, but more work (and tests)
> are required.
>
> Thanks,
> Mauro
I can confirm that the bolding in struct hrtimer_sleeper * futex_setup_timer()
is fixed after applying this patch.
OTOH, the bolding for int seq_open() remains as it was previously.
The only way that I could eliminate it was a small source file patch:
---
fs/seq_file.c | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
--- linux-next-20201030.orig/fs/seq_file.c
+++ linux-next-20201030/fs/seq_file.c
@@ -47,7 +47,9 @@ static void *seq_buf_alloc(unsigned long
* ERR_PTR(error). In the end of sequence they return %NULL. ->show()
* returns 0 in case of success and negative number in case of error.
* Returning SEQ_SKIP means "discard this element and move on".
- * Note: seq_open() will allocate a struct seq_file and store its
+ *
+ * Note:
+ * seq_open() will allocate a struct seq_file and store its
* pointer in @file->private_data. This pointer should not be modified.
*/
int seq_open(struct file *file, const struct seq_operations *op)
> [PATCH] scripts: kernel-doc: better handle spaces after section markups
>
> Better handle things like:
>
> * Return: foo
> * description
>
> Suggested-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index f699cf05d409..a91a2420cccf 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
> my $doc_decl = $doc_com . '(\w+)';
> # @params and a strictly limited set of supported section names
> my $doc_sect = $doc_com .
> - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
> + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
> my $doc_content = $doc_com_body . '(.*)';
> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> my $doc_inline_start = '^\s*/\*\*\s*$';
> @@ -865,8 +865,21 @@ sub output_highlight_rst {
> my $in_literal = 0;
> my $litprefix;
> my $block = "";
> + my $spaces = "";
> + my $first = 1;
>
> foreach $line (split "\n",$input) {
> + if ($first) {
> + $spaces = $1 if ($line =~ (m/^(\s+)/));
> + $first = 0;
> + }
> +
> + if ($spaces ne "") {
> + if (!($line =~ s/^$spaces//)) {
> + $spaces = "";
> + }
> + }
> +
> #
> # If we're in a literal block, see if we should drop out
> # of it. Otherwise pass the line straight through unmunged.
> @@ -2135,8 +2148,9 @@ sub process_body($$) {
> }
>
> if (/$doc_sect/i) { # case insensitive for supported section names
> + my $spaces = "$1$2";
> $newsection = $1;
> - $newcontents = $2;
> + $newcontents = $3;
>
> # map the supported section names to the canonical names
> if ($newsection =~ m/^description$/i) {
> @@ -2161,11 +2175,20 @@ sub process_body($$) {
>
> $in_doc_sect = 1;
> $state = STATE_BODY;
> - $contents = $newcontents;
> $new_start_line = $.;
> - while (substr($contents, 0, 1) eq " ") {
> - $contents = substr($contents, 1);
> +
> + if ($newsection =~ m/(return|note)/i) {
> + $spaces =~ s/\S/ /g;
> + $newcontents = $spaces . $newcontents;
> + $newcontents =~ s/^\s+$//;
> + $contents = $newcontents;
> + } else {
> + $contents = $newcontents;
> + while (substr($newcontents, 0, 1) eq " ") {
> + $newcontents = substr($newcontents, 1);
> + }
> }
> +
> if ($contents ne "") {
> $contents .= "\n";
> }
>
>
--
~Randy
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-10-30 17:30 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-30 3:17 excess bolding in html Randy Dunlap
2020-10-30 7:37 ` Mauro Carvalho Chehab
2020-10-30 11:31 ` Matthew Wilcox
2020-10-30 12:28 ` Markus Heiser
2020-10-30 12:53 ` Matthew Wilcox
2020-10-30 14:00 ` Mauro Carvalho Chehab
2020-10-30 14:19 ` [PATCH RFC] scripts: kernel-doc: better handle spaces after section markups Mauro Carvalho Chehab
2020-10-30 17:30 ` excess bolding in html Randy Dunlap
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.