Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Randy Dunlap
2009-08-24T19:57:36Z

On Mon, 24 Aug 2009 12:06:54 -0700 (PDT) Johannes Weiner wrote:

> On Wed, Aug 19, 2009 at 04:21:23PM -0700, Randy Dunlap wrote:
> > 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.
>
> Yeah, I forgot to actually collect empty lines in the documentation
> bodies when changing that conditional. Stupid. I fixed it in the
> attached version.

Thanks. I had spent some time on it but I hadn't quite found the magical
incantation to preserve the exact same output as without the patch, but your
patch now does that.

I'll add this to my kernel-doc quilt patch series.

Oh, one question below...

> ---
> 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>
> ---
>
> 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..d8b3641 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,19 @@ 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 = "";
> + } else {
> + $contents .= "\n";
> + }
> + $in_purpose = 0;
> + } elsif ($in_purpose == 1) {
> + # Continued declaration purpose
> + chomp($declaration_purpose);
> + $declaration_purpose .= " " . $1;

Why shouldn't this be:
$declaration_purpose .= " " . xml_escape($1);
?

> } else {
> $contents .= $1 . "\n";
> }

---
~Randy
LPC 2009, Sept. 23-25, Portland, Oregon