Better handle things like:
* Return: foo
* description
Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
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
