Re: excess bolding in html

[Mauro Carvalho Chehab <mchehab@kernel.org>]

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";
 	}