Re: Since and deprecated

[Matthias Clasen <maclas gmx de>]

Thanks for the review. Here is a new patch incorporating your comments.
I'll probably commit it within the next week if nobody complains.

Matthias

Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.62
diff -u -b -B -p -r1.62 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	12 Nov 2002 10:21:27 -0000	1.62
+++ gtkdoc-mkdb.in	25 Nov 2002 23:51:10 -0000
@@ -96,7 +96,6 @@ if (lc($OUTPUT_FORMAT) eq "xml") {
     $empty_element_end = "/>";
 
     if ($MAIN_SGML_FILE && -e $MAIN_SGML_FILE) {
-	print "scanning $MAIN_SGML_FILE";
         open(INPUT, "<$MAIN_SGML_FILE") || die "Can't open $MAIN_SGML_FILE";
 	$doctype_header = "";
 	while (<INPUT>) {
@@ -166,6 +165,7 @@ my %DeclarationTypes;
 my %DeclarationConditional;
 my %DeclarationOutput;
 my %Deprecated;
+my %Since;
 
 # These global hashes store the existing documentation.
 my %SymbolDocs;
@@ -628,14 +628,22 @@ sub OutputMacro {
 	$desc .= "</programlisting>\n";
     }
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
     $desc .= &OutputParamDescriptions ("MACRO", $symbol);
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -659,13 +667,21 @@ sub OutputTypedef {
 	$desc .= "<programlisting>$declaration</programlisting>\n";
     }
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -736,8 +752,13 @@ sub OutputStruct {
     $decl_out = &CreateValidSGML ($decl_out);
     $desc .= "<programlisting>$decl_out</programlisting>\n";
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -790,6 +811,9 @@ EOF
     
 	$desc .= "</variablelist>";
     }
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -810,8 +834,13 @@ sub OutputEnum {
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -857,6 +886,9 @@ EOF
 	$desc .= "</variablelist>";
     }
 
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -877,13 +909,21 @@ sub OutputUnion {
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -915,13 +955,21 @@ sub OutputVariable {
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -1073,8 +1121,13 @@ sub OutputFunction {
     $synop .= ");\n";
     $desc  .= ");</programlisting>\n";
 
-    if ($Deprecated{$symbol}) {
-        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
+    if (exists $Deprecated{$symbol}) {
+	$desc .= "<warning>\n";
+	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
+	if ($Deprecated{$symbol} ne "") {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -1082,6 +1135,9 @@ sub OutputFunction {
     }
 
     $desc .= &OutputParamDescriptions ("FUNCTION", $symbol);
+    if (exists $Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -1887,14 +1943,12 @@ sub ReadSourceDocumentation {
 sub ScanSourceFile {
     my ($file) = @_;
 
-#    print "Scanning source file: $file\n";
-
     open (SRCFILE, $file)
 	|| die "Can't open $file: $!";
     my $in_comment_block = 0;
     my $symbol;
-    my ($in_description, $in_return);
-    my ($description, $return_desc, $return_start);
+    my ($in_description, $in_return, $in_since, $in_deprecated);
+    my ($description, $return_desc, $return_start, $since_desc, $deprecated_desc);
     my $current_param;
     my $ignore_returns;
     my @params;
@@ -1911,8 +1965,12 @@ sub ScanSourceFile {
 		$symbol = "";
 		$in_description = 0;
 		$in_return = 0;
+		$in_since = 0;
+		$in_deprecated = 0;
 		$description = "";
 		$return_desc = "";
+		$since_desc = "";
+		$deprecated_desc = "";
 		$current_param = -1;
 		$ignore_returns = 0;
 		@params = ();
@@ -1922,7 +1980,6 @@ sub ScanSourceFile {
 
 	# We're in a comment block. Check if we've found the end of it.
 	if (m%^\s*\*+/%) {
-#	    print "Found comment block end: $symbol\n";
 	    if (!$symbol) {
 		print <<EOF;
 WARNING: symbol name not found in comment block.
@@ -1943,6 +2000,21 @@ EOF
 
 		$SourceSymbolDocs{$symbol} = $description;
 		$SourceSymbolParams{$symbol} = [ @params ];
+
+		if ($since_desc) {
+		    $Since{$symbol} = &ConvertSGMLChars ($since_desc);
+		}
+
+		if ($deprecated_desc) {
+		    if (exists $Deprecated{$symbol}) {
+		    }
+		    else {
+			print <<EOF;
+WARNING: Unguarded $symbol deprecated in inline comments
+EOF
+		    }
+		    $Deprecated{$symbol} = &ConvertSGMLChars ($deprecated_desc);
+		}
 	    }
 
 	    $in_comment_block = 0;
@@ -1972,12 +2044,54 @@ EOF
 		$description .= $return_start . $return_desc;
 		$return_start = $1;
 		$return_desc = $';
+	    } elsif (m%^\s*since:%i) {
+		$since_desc = $';
+		$in_since = 1;
+		$in_return = 0;
+	    } elsif (m%^\s*deprecated:%i) {
+		$deprecated_desc = $';
+		$in_deprecated = 1;
+		$in_return = 0;
 	    } else {
 		$return_desc .= $_;
 	    }
 	    next;
 	}
 
+	if ($in_since) {
+	    if (m%^\s*(returns:|return\s+value:|returns\s*)%i) {
+		$description .= $return_start . $return_desc;
+		$return_start = $1;
+		$return_desc = $';
+		$in_return = 1;
+		$in_since = 0;
+	    } elsif (m%^\s*deprecated:%i) {
+		$deprecated_desc = $';
+		$in_deprecated = 1;
+		$in_since = 0;
+	    } else {
+		$since_desc .= $_;
+	    }
+	    next;
+	}
+
+	if ($in_deprecated) {
+	    if (m%^\s*(returns:|return\s+value:|returns\s*)%i) {
+		$description .= $return_start . $return_desc;
+		$return_start = $1;
+		$return_desc = $';
+		$in_return = 1;
+		$in_deprecated = 0;
+	    } elsif (m%^\s*since:%i) {
+		$since_desc = $';
+		$in_since = 1;
+		$in_deprecated = 0;
+	    } else {
+		$deprecated_desc .= $_;
+	    }
+	    next;
+	}
+
 	# If we're in the description part, check for the 'Return' line.
 	# If that isn't found, add the text to the end.
 	if ($in_description) {
@@ -1985,12 +2099,21 @@ EOF
 	    s%^\s*Description:%%;
 
 	    if (!$ignore_returns && m%^\s*(returns:|return\s+value:|returns\s*)%i) {
-#		print "RETURNS: $_";
 		$return_start = $1;
 		$return_desc = $';
 		$in_return = 1;
 		next;
 	    }
+	    elsif (m%^\s*since:%i) {
+		$since_desc = $';
+		$in_since = 1;
+		next;
+	    }
+	    elsif (m%^\s*deprecated:%i) {
+		$deprecated_desc = $';
+		$in_deprecated = 1;
+		next;
+	    }
 
 	    $description .= $_;
 	    next;
@@ -2300,7 +2423,9 @@ sub ReadDeclarationsFile {
 		    if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
 			# Ignore it.
 		    } elsif ($declaration_type eq 'FUNCTION') {
-                        $Deprecated{$declaration_name} = $is_deprecated;
+			if ($is_deprecated) {
+			    $Deprecated{$declaration_name} = "";
+			}
 			$Declarations{$declaration_name} = $declaration;
 			$DeclarationTypes{$declaration_name} = $declaration_type;
 		    } elsif ($DeclarationTypes{$declaration_name}
@@ -2308,7 +2433,9 @@ sub ReadDeclarationsFile {
 			# If the existing declaration is empty override it.
 			if ($declaration_type eq 'STRUCT') {
 			    if ($Declarations{$declaration_name} =~ m/^\s*$/) {
-                                $Deprecated{$declaration_name} = $is_deprecated;
+				if ($is_deprecated) {
+				    $Deprecated{$declaration_name} = "";
+				}
 				$Declarations{$declaration_name} = $declaration;
 			    } elsif ($declaration =~ m/^\s*$/) {
 				# Ignore an empty declaration.
@@ -2325,7 +2452,9 @@ sub ReadDeclarationsFile {
 			print "ERROR: $declaration_name has multiple definitions\n";
 		    }
 		} else {
-                    $Deprecated{$declaration_name} = $is_deprecated;
+		    if ($is_deprecated) {
+			$Deprecated{$declaration_name} = "";
+		    }
 		    $Declarations{$declaration_name} = $declaration;
 		    $DeclarationTypes{$declaration_name} = $declaration_type;
 		}