lkml.org 
[lkml]   [2020]   [Oct]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH RFC] scripts: kernel-doc: better handle spaces after section markups
Date
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

\
 
 \ /
  Last update: 2020-10-30 15:19    [W:0.266 / U:0.168 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site