Messages in this thread | | | Date | Wed, 19 Aug 2009 16:21:23 -0700 | From | Randy Dunlap <> | Subject | Re: [PATCH] Add kerneldoc for flush_scheduled_work() |
| |
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"; > }
| |