GNOME.org
 

Re: Interface Stability (was Re: xxx-undocumented.txt)


Damon:

Okay, I've updated the patch.  Now it works as follows:

If the user specifies "--default-stability-level=LVL" argument, or if the
user has defined the following section in the tmpl file:

  <!-- ##### SECTION Stability_Level ##### -->
  LVL

Then the following appears at the top of the generated page, just under
the title/description and before the Synopsis.

  Stability Level
  LVL, unless otherwise indicated

If the user defines a @Stability argument in the tmpl file or a
"* Stability: LVL" comment in the docs for a given interface, then the
interface includes the following text in the generated output.

  Stability Level: LVL

I think this addresses all the concerns.  This makes it easy for the module
maintainer to manage.  They can define defaults at the gtkdoc-mkdb command
line, or in the tmpl file.  For interfaces that are exceptions, it is only
necessary to add the Stability tag to the specific interfaces.

Brian

Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.108
diff -r1.108 gtkdoc-mkdb.in
50a51
> my $DEFAULT_STABILITY;
62a64
> 	      'default-stability' => \$DEFAULT_STABILITY,
64c66
< GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version", "outputallsymbols", "main-sgml-file:s", "help", "sgml-mode", "output-format:s");
---
> GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version", "outputallsymbols", "main-sgml-file:s", "help", "sgml-mode", "default-stability:s", "output-format:s");
74a77,82
> if ($DEFAULT_STABILITY && $DEFAULT_STABILITY !~ /^\s*Stable\s*$/ &&
>     $DEFAULT_STABILITY !~ /^\s*Private\s*$/ &&
>     $DEFAULT_STABILITY !~ /^\s*Unstable\s*$/) {
>     $PRINT_HELP = 1;
> }
> 
85a94,95
>     print "\n--stability-level=LVL  Specify default Stability Level.  Valid values are";
>     print "\n                       Stable, Unstable, or Private."; 
173a184
> my %StabilityLevel;
550a562
> 
760a773,776
> 
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
794a811,813
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
963a983,985
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
1034a1057,1059
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
1065a1091,1093
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
1107a1136,1138
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
1289a1321,1323
>     if (exists $StabilityLevel{$symbol}) {
> 	$desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
>     }
1411a1446,1464
>     my $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
>     if (!defined ($stability) || $stability =~ m/^\s*$/) {
> 	$stability = "";
>     } else {
> 	$stability = &ExpandAbbreviations($stability);
> 	if ($stability !~ /^\s*Stable\s*$/ && $stability !~ /^\s*Private\s*$/ &&
>             $stability !~ /^\s*Unstable\s*$/) {
> 		print <<EOF;
> WARNING: Section Stability Level for $file is $stability.  It should be
> one of the following values:  Stable, Unstable, or Private.
> EOF
> 	}
> #	print "Found stability: $stability";
>     }
>     if ($stability) {
> 	$stability = "<refsect1>\n<title>Stability Level</title>\n$stability, unless otherwise indicated\n</refsect1>\n";
>     } elsif ($DEFAULT_STABILITY) {
> 	$stability = "<refsect1>\n<title>Stability Level</title>\n$DEFAULT_STABILITY, unless otherwise indicated\n</refsect1>\n";
>     }
1459a1513
> $stability
1738c1792,1797
< 	$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.";
> 	}
1740a1800
> 	    $note =~ s/^\s*([0-9\.]+)\s*:\s*//;
2098a2159,2161
> 	    if (exists $StabilityLevel{$symbol}) {
> 	      $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
> 	    }
2209a2273,2275
> 	    if (exists $StabilityLevel{$symbol}) {
> 	      $arg_desc .= "<para>Stability Level $StabilityLevel{$symbol}</para>\n";
> 	    }
2244c2310
< #############################################################################
---
> #############m###############################################################
2306,2307c2372,2373
<     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);
2329a2396,2397
> 		$stability_desc = "";
> 		$in_stability = 0;
2364a2433,2447
> 		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
> 			}
> 		}
> 
2409a2493,2496
> 	    } elsif (m%^\s*stability:%i) {
> 		$stability_desc = $';
> 		$in_stability = 1;
> 		$in_return = 0;
2430a2518,2521
> 	    } elsif (m%^\s*stability:%i) {
> 		$stability_desc = $';
> 		$in_stability = 1;
> 		$in_since = 0;
2436a2528,2548
> 	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;
> 	}
> 
2447a2560,2563
> 	    } elsif (m%^\s*stability:%i) {
> 		$stability_desc = $';
> 		$in_stability = 1;
> 		$in_deprecated = 0;
2474a2591,2594
> 	    } elsif (m%^\s*stability:%i) {
> 		$stability_desc = $';
> 		$in_stability = 1;
> 		next;
2538c2658
<           if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also)/) {
---
>           if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level)/) {
2984a3105
>     my $section_stability = "";
2995c3116,3118
< 		|| $symbol eq "See_Also") {
---
> 		|| $symbol eq "See_Also"
> 		|| $symbol eq "Stability_Level") {
> 
2999a3123,3126
> 	    if ($symbol eq "Stability_Level") {
> 		$section_stability = $symbol;
> 	    }
> 
3004a3132
> 
3019a3148,3165
> 
> 		    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;
> 			}
> 		    }
3079a3226
> 
3090a3238,3255
> 		    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
> 		    }
Index: gtkdoc-mktmpl.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mktmpl.in,v
retrieving revision 1.41
diff -r1.41 gtkdoc-mktmpl.in
421a422
> 	$output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
440a442
> 	$output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
454a457
> 	$output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
464a468
> 	$output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
582c586
<     my ($short_desc, $long_desc, $see_also);
---
>     my ($short_desc, $long_desc, $see_also, $stability);
605a610,616
>     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Stability_Level"})) {
> 	$stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
> 	delete $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
>     } else {
> 	$stability = "";
>     }
> 
625a637,639
> <!-- ##### SECTION Stability_Level ##### -->
> $stability
> 
1025c1039,1040
< 		|| $symbol eq "See_Also") {
---
> 		|| $symbol eq "See_Also"
> 		|| $symbol eq "Stability_Level") {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]