Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Randy Dunlap <randy.dunlap@oracle.com>]

Johannes Weiner wrote:
>> Yeah, it's the terminating **/ which matches $doc_cont.  I will try to
>> send an updated version this evening.
> 
> I got completely rid of the extra re.  Just parse a non-empty content
> line following the declaration purpose immediately as continuation.
> 
> It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and
> for stuff that had continuation lines before, it does what's expected
> - e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
> 
> It behaves differently for broken docs
> (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that
> shouldn't matter.

Right, no problem on that one (for which I sent Andrew a patch some
time ago).

> I didn't find any other misbehaviour when checking random samples.

It's very close.  I only checked/compared one docbook: mac80211.
There is some kind of paragraph end handling difference.

In processing include/net/mac80211.h, struct ieee80211_tx_info,
without the patch, it ends with:

This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened

The TX control's sta pointer is only valid during the ->tx call, it may be NULL.

and with the patch, those 2 paragraphs are run together:

This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened The TX control's sta pointer is only valid during the ->tx call, it may be NULL.



I don't think that this will be difficult to find/fix...

Thanks.

> ---
> From: Johannes Weiner <hannes@cmpxchg.org>
> Subject: kernel-doc: allow multi-line declaration purpose descriptions
> 
> Allow the short description after symbol name and dash in a kernel-doc
> comment to span multiple lines, e.g. like this:
> 
> 	/**
> 	 * unmap_mapping_range - unmap the portion of all mmaps in the
> 	 *	specified address_space corresponding to the specified
> 	 *	page range in the underlying file.
> 	 * @mapping: the address space containing mmaps to be unmapped.
> 	 * ...
> 	 */
> 
> The short description ends with a parameter description, an empty line
> or the end of the comment block.
> 
> Signed-off-by: Johannes Weiner <hannes@cmpxchg.org>
> ---
>  Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
>  scripts/kernel-doc                      |   19 ++++++++++++++-----
>  2 files changed, 17 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
> index 4d04572..348b9e5 100644
> --- a/Documentation/kernel-doc-nano-HOWTO.txt
> +++ b/Documentation/kernel-doc-nano-HOWTO.txt
> @@ -66,7 +66,9 @@ Example kernel-doc function comment:
>   * The longer description can have multiple paragraphs.
>   */
>  
> -The first line, with the short description, must be on a single line.
> +The short description following the subject can span multiple lines
> +and ends with an @argument description, an empty line or the end of
> +the comment block.
>  
>  The @argument descriptions must begin on the very next line following
>  this opening short function description line, with no intervening
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index b52d340..6194ef5 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1995,6 +1995,7 @@ sub process_file($) {
>      my $identifier;
>      my $func;
>      my $descr;
> +    my $in_purpose = 0;
>      my $initial_section_counter = $section_counter;
>  
>      if (defined($ENV{'SRCTREE'})) {
> @@ -2044,6 +2045,7 @@ sub process_file($) {
>  		    $descr =~ s/\s*$//;
>  		    $descr =~ s/\s+/ /;
>  		    $declaration_purpose = xml_escape($descr);
> +		    $in_purpose = 1;
>  		} else {
>  		    $declaration_purpose = "";
>  		}
> @@ -2090,6 +2092,7 @@ sub process_file($) {
>  		}
>  
>  		$in_doc_sect = 1;
> +		$in_purpose = 0;
>  		$contents = $newcontents;
>  		if ($contents ne "") {
>  		    while ((substr($contents, 0, 1) eq " ") ||
> @@ -2119,11 +2122,17 @@ sub process_file($) {
>  	    } elsif (/$doc_content/) {
>  		# miguel-style comment kludge, look for blank lines after
>  		# @parameter line to signify start of description
> -		if ($1 eq "" &&
> -			($section =~ m/^@/ || $section eq $section_context)) {
> -		    dump_section($file, $section, xml_escape($contents));
> -		    $section = $section_default;
> -		    $contents = "";
> +		if ($1 eq "") {
> +		    if ($section =~ m/^@/ || $section eq $section_context) {
> +			dump_section($file, $section, xml_escape($contents));
> +			$section = $section_default;
> +			$contents = "";
> +		    }
> +		    $in_purpose = 0;
> +		} elsif ($in_purpose == 1) {
> +		    # Continued declaration purpose
> +		    chomp($declaration_purpose);
> +		    $declaration_purpose .= " " . $1;
>  		} else {
>  		    $contents .= $1 . "\n";
>  		}