Re: Interface Stability (was Re: xxx-undocumented.txt)
- From: Brian Cameron <Brian Cameron Sun COM>
- To: Damon Chaplin <damon karuna uklinux net>
- Cc: gtk-doc-list gnome org, sun-sac-foss-ext Sun COM, Matthias Clasen <mclasen redhat com>
- Subject: Re: Interface Stability (was Re: xxx-undocumented.txt)
- Date: Thu, 20 Jan 2005 21:00:45 -0600
Damon:
Attached find a patch that implements Stability Levels with the following type
of command:
Stability: [Stable|Unstable|Private]
With error checking. If the stability level specified is not one of the above,
it accepts it but prints a warning.
The patch also supports specifying the version # of a deprecation in this
format:
Deprecated: x.y.z: String
Where x.y.z is any combination of digits and "." characters.
I think I got the patch right, but you should let me know if you want me
to make any changes. Perhaps there are better ways to do some of the
things I'm doing.
In your last email you highlighted information about how to document
ENVIRONMENT variables, data structures, enumerations, and files. I
believe Stefan asked if he could do some of this work and I want to check
to see if he wants to do these tasks. If not, then I'll go ahead. Ping.
Brian
? gtkdoc-mkdb.in-orig
? gtkdoc-stability-deprecated.diff
Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.108
diff -u -r1.108 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in 9 Jan 2005 17:12:31 -0000 1.108
+++ gtkdoc-mkdb.in 21 Jan 2005 02:53:01 -0000
@@ -171,6 +171,7 @@
my %DeclarationOutput;
my %Deprecated;
my %Since;
+my %StabilityLevel;
my %StructHasTypedef;
# These global hashes store the existing documentation.
@@ -758,6 +759,10 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -792,6 +797,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -961,6 +969,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -1032,6 +1043,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -1063,6 +1077,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -1105,6 +1122,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -1287,6 +1307,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>\n";
return ($synop, $desc);
}
@@ -1735,9 +1758,15 @@
my $note = "";
if (exists $Deprecated{$symbol}) {
$desc .= "<warning>";
- $desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
+
+ if ($Deprecated{$symbol} =~ /^[\s]*([0-9\.]+)[\s]*:/) {
+ $desc .= "<para><literal>$symbol</literal> has been deprecated since version $1 should not be used in newly-written code.";
+ } else {
+ $desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
+ }
if ($Deprecated{$symbol} ne "") {
$note = &ExpandAbbreviations($Deprecated{$symbol});
+ $note =~ s/([0-9\.]+)[\s]*:[\s]*//;
$note =~ s/^\s+//;
$note =~ s/\s+$//;
$note =~ s%\n{2,}%\n</para>\n<para>\n%g;
@@ -2096,6 +2125,9 @@
if (exists $Since{$symbol}) {
$desc .= "<para>Since $Since{$symbol}</para>";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
+ }
$desc .= "</refsect2>";
}
}
@@ -2207,6 +2239,9 @@
if (exists $Since{$symbol}) {
$arg_desc .= "<para>Since $Since{$symbol}</para>\n";
}
+ if (exists $StabilityLevel{$symbol}) {
+ $arg_desc .= "<para>Stability Level $StabilityLevel{$symbol}</para>\n";
+ }
$arg_desc .= "</refsect2>\n";
if ($flags =~ m/c/) {
@@ -2303,8 +2338,8 @@
|| die "Can't open $file: $!";
my $in_comment_block = 0;
my $symbol;
- my ($in_description, $in_return, $in_since, $in_deprecated);
- my ($description, $return_desc, $return_start, $since_desc, $deprecated_desc);
+ my ($in_description, $in_return, $in_since, $in_stability, $in_deprecated);
+ my ($description, $return_desc, $return_start, $since_desc, $stability_desc, $deprecated_desc);
my $current_param;
my $ignore_returns;
my @params;
@@ -2327,6 +2362,7 @@
$description = "";
$return_desc = "";
$since_desc = "";
+ $stability_desc = "";
$deprecated_desc = "";
$current_param = -1;
$ignore_returns = 0;
@@ -2362,6 +2398,21 @@
$Since{$symbol} = &ConvertSGMLChars ($since_desc);
}
+ if ($stability_desc) {
+ $StabilityLevel{$symbol} = &ConvertSGMLChars ($stability_desc);
+
+ $StabilityLevel{$symbol} =~ s/^\s*//;
+ $StabilityLevel{$symbol} =~ s/\s*$//;
+ if ($StabilityLevel{$symbol} !~ /^\s*Stable\s*$/ &&
+ $StabilityLevel{$symbol} !~ /^\s*Private\s*$/ &&
+ $StabilityLevel{$symbol} !~ /^\s*Unstable\s*$/) {
+ print <<EOF;
+WARNING: Stability level for $symbol is $StabilityLevel{$symbol}. It should be
+one of the following values: Stable, Unstable, or Private.
+EOF
+ }
+ }
+
if ($deprecated_desc) {
if (exists $Deprecated{$symbol}) {
}
@@ -2407,6 +2458,10 @@
$since_desc = $';
$in_since = 1;
$in_return = 0;
+ } elsif (m%^\s*stability:%i) {
+ $stability_desc = $';
+ $in_stability = 1;
+ $in_return = 0;
} elsif (m%^\s*deprecated:%i) {
$deprecated_desc = $';
$in_deprecated = 1;
@@ -2428,12 +2483,37 @@
$deprecated_desc = $';
$in_deprecated = 1;
$in_since = 0;
+ } elsif (m%^\s*stability:%i) {
+ $stability_desc = $';
+ $in_stability = 1;
+ $in_since = 0;
} else {
$since_desc .= $_;
}
next;
}
+ if ($in_stability) {
+ if (m%^\s*(returns:|return\s+value:|returns\s*)%i) {
+ $description .= $return_start . $return_desc;
+ $return_start = $1;
+ $return_desc = $';
+ $in_return = 1;
+ $in_stability = 0;
+ } elsif (m%^\s*deprecated:%i) {
+ $deprecated_desc = $';
+ $in_deprecated = 1;
+ $in_stability = 0;
+ } elsif (m%^\s*since:%i) {
+ $since_desc = $';
+ $in_since = 1;
+ $in_stability = 0;
+ } else {
+ $stability_desc .= $_;
+ }
+ next;
+ }
+
if ($in_deprecated) {
if (m%^\s*(returns:|return\s+value:|returns\s*)%i) {
$description .= $return_start . $return_desc;
@@ -2445,6 +2525,10 @@
$since_desc = $';
$in_since = 1;
$in_deprecated = 0;
+ } elsif (m%^\s*stability:%i) {
+ $stability_desc = $';
+ $in_stability = 1;
+ $in_deprecated = 0;
} else {
$deprecated_desc .= $_;
}
@@ -2472,6 +2556,10 @@
$deprecated_desc = $';
$in_deprecated = 1;
next;
+ } elsif (m%^\s*stability:%i) {
+ $stability_desc = $';
+ $in_stability = 1;
+ next;
}
$description .= $_;
@@ -3017,6 +3105,23 @@
$current_param -= 2;
}
}
+ if ($current_param > 0) {
+ if ($params[$current_param - 1] eq "Stability") {
+ $StabilityLevel{$current_symbol} = pop (@params);
+ $StabilityLevel{$current_symbol} =~ s/^\s*//;
+ $StabilityLevel{$current_symbol} =~ s/\s*$//;
+ if ($StabilityLevel{$current_symbol} !~ /^\s*Stable\s*$/ &&
+ $StabilityLevel{$current_symbol} !~ /^\s*Private\s*$/ &&
+ $StabilityLevel{$current_symbol} !~ /^\s*Unstable\s*$/) {
+ print <<EOF;
+WARNING: Stability level for $current_symbol is $StabilityLevel{$current_symbol}. It should be
+one of the following values: Stable, Unstable, or Private.
+EOF
+ }
+ pop (@params);
+ $current_param -= 2;
+ }
+ }
# look for deprecated again to support both orders
if ($current_param > 0) {
if ($params[$current_param - 1] eq "Deprecated") {
@@ -3088,6 +3193,23 @@
if ($current_param > 0) {
if ($params[$current_param - 1] eq "Since") {
$Since{$current_symbol} = pop (@params);
+ pop (@params);
+ $current_param -= 2;
+ }
+ }
+ if ($current_param > 0) {
+ if ($params[$current_param - 1] eq "Stability") {
+ $StabilityLevel{$current_symbol} = pop (@params);
+ $StabilityLevel{$current_symbol} =~ s/^\s*//;
+ $StabilityLevel{$current_symbol} =~ s/\s*$//;
+ if ($StabilityLevel{$current_symbol} !~ /^\s*Stable\s*$/ &&
+ $StabilityLevel{$current_symbol} !~ /^\s*Private\s*$/ &&
+ $StabilityLevel{$current_symbol} !~ /^\s*Unstable\s*$/) {
+ print <<EOF;
+WARNING: Stability level for $current_symbol is $StabilityLevel{$current_symbol}. It should be
+one of the following values: Stable, Unstable, or Private.
+EOF
+ }
pop (@params);
$current_param -= 2;
}
Index: gtkdoc-mktmpl.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mktmpl.in,v
retrieving revision 1.41
diff -u -r1.41 gtkdoc-mktmpl.in
--- gtkdoc-mktmpl.in 9 Jan 2005 16:10:04 -0000 1.41
+++ gtkdoc-mktmpl.in 21 Jan 2005 02:53:03 -0000
@@ -419,6 +419,7 @@
}
$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
+ $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
$output .= &OutputOldParams ($symbol);
$output .= "\n";
}
@@ -438,6 +439,7 @@
$output .= &OutputParam ($symbol, "Returns", $template_exists, 0, "");
$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
+ $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
$output .= &OutputOldParams ($symbol);
$output .= "\n";
}
@@ -452,6 +454,7 @@
}
$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
+ $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
}
if ($type eq "ENUM") {
@@ -462,6 +465,7 @@
}
$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
+ $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
}
$output .= "\n";
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
