Since and deprecated

[Matthias Clasen <maclas gmx de>]

Here is a patch which supports Since: and Deprecated: lines in inline
doc comments like:

/**
 * do_something:
 * @arg1: first arg
 * @arg2: second arg
 *
 * Does something sometimes.
 *
 * Return: something else
 *
 * Since: 3.4.5
 *
 * Deprecated: This is completely useless. Use something else.
 **/

The Since: information is currently just tacked at the very end of the
refsection2, as <para>Since 3.4.5</para>, the deprecation information is
added after the autogenerated deprecation statement, but inside the
warning tag. gtk-doc will warn if it finds inline deprecation
information for symbols which are not guarded by a deprecation #define.

Note that the repetitive aspects of the patch really point to some
necessary refactoring of the gtk-doc code.

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	15 Nov 2002 14:49:48 -0000
@@ -96,7 +96,7 @@ if (lc($OUTPUT_FORMAT) eq "xml") {
     $empty_element_end = "/>";
 
     if ($MAIN_SGML_FILE && -e $MAIN_SGML_FILE) {
-	print "scanning $MAIN_SGML_FILE";
+	print "scanning $MAIN_SGML_FILE\n";
         open(INPUT, "<$MAIN_SGML_FILE") || die "Can't open $MAIN_SGML_FILE";
 	$doctype_header = "";
 	while (<INPUT>) {
@@ -166,6 +166,7 @@ my %DeclarationTypes;
 my %DeclarationConditional;
 my %DeclarationOutput;
 my %Deprecated;
+my %Since;
 
 # These global hashes store the existing documentation.
 my %SymbolDocs;
@@ -629,13 +630,21 @@ sub OutputMacro {
     }
 
     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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
     $desc .= &OutputParamDescriptions ("MACRO", $symbol);
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -660,12 +669,20 @@ sub OutputTypedef {
     }
 
     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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -737,7 +754,12 @@ sub OutputStruct {
     $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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -790,6 +812,9 @@ EOF
     
 	$desc .= "</variablelist>";
     }
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -811,7 +836,12 @@ sub OutputEnum {
     $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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -857,6 +887,9 @@ EOF
 	$desc .= "</variablelist>";
     }
 
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -878,12 +911,20 @@ sub OutputUnion {
     $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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -916,12 +957,20 @@ sub OutputVariable {
     $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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -1074,7 +1123,12 @@ sub OutputFunction {
     $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";
+	$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 1) {
+	    $desc .= "<para>$Deprecated{$symbol}</para>";
+	}
+	$desc .= "</warning>\n";
     }
 
     if (defined ($SymbolDocs{$symbol})) {
@@ -1082,6 +1136,9 @@ sub OutputFunction {
     }
 
     $desc .= &OutputParamDescriptions ("FUNCTION", $symbol);
+    if ($Since{$symbol}) {
+	$desc .= "<para>Since $Since{$symbol}</para>";
+    }
     $desc .= "</refsect2>\n";
     return ($synop, $desc);
 }
@@ -1893,8 +1950,8 @@ sub ScanSourceFile {
 	|| 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 +1968,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 = ();
@@ -1943,6 +2004,23 @@ EOF
 
 		$SourceSymbolDocs{$symbol} = $description;
 		$SourceSymbolParams{$symbol} = [ @params ];
+
+		if ($since_desc) {
+		    $since_desc = &ConvertSGMLChars ($since_desc);
+		    $Since{$symbol} = $since_desc;
+		}
+
+		if ($deprecated_desc) {
+		    if ($Deprecated{$symbol}) {
+		    }
+		    else {
+			print <<EOF;
+WARNING: Unguarded $symbol deprecated in inline comments
+EOF
+		    }
+		    $deprecated_desc = &ConvertSGMLChars ($deprecated_desc);
+		    $Deprecated{$symbol} = $deprecated_desc;
+		}
 	    }
 
 	    $in_comment_block = 0;
@@ -1972,12 +2050,58 @@ EOF
 		$description .= $return_start . $return_desc;
 		$return_start = $1;
 		$return_desc = $';
+	    } elsif (m%^\s*since:%i) {
+#		print "SINCE after return: $_";
+		$since_desc = $';
+		$in_since = 1;
+		$in_return = 0;
+	    } elsif (m%^\s*deprecated:%i) {
+#		print "DEPRECATED after return: $_";
+		$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) {
+#		print "DEPRECATED after since: $_";
+		$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) {
+#		print "SINCE after deprecated: $_";
+		$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) {
@@ -1989,6 +2113,18 @@ EOF
 		$return_start = $1;
 		$return_desc = $';
 		$in_return = 1;
+		next;
+	    }
+	    elsif (m%^\s*since:%i) {
+#		print "SINCE: $_";
+		$since_desc = $';
+		$in_since = 1;
+		next;
+	    }
+	    elsif (m%^\s*deprecated:%i) {
+#		print "DEPRECATED: $_";
+		$deprecated_desc = $';
+		$in_deprecated = 1;
 		next;
 	    }