| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20090824190653.GA2197@cmpxchg.org>
Date: Mon, 24 Aug 2009 21:06:54 +0200
From: Johannes Weiner <hannes@...xchg.org>
To: Randy Dunlap <randy.dunlap@...cle.com>
Cc: James Bottomley <James.Bottomley@...senPartnership.com>,
stern@...land.harvard.edu, akpm@...ux-foundation.org,
apw@...onical.com, mingo@...e.hu, linux-kernel@...r.kernel.org,
peterz@...radead.org
Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work()
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.
---
From: Johannes Weiner <hannes@...xchg.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@...xchg.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;
} else {
$contents .= $1 . "\n";
}
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists