Re: Since and deprecated

[Matthias Clasen <maclas gmx de>]

Here is a patch supporting since and deprecated info in template files.
You can add 

@Since: 2.2
@Deprecated: Use foo() instead. 

at the end of a "parameter" list in a template. The also works for
structs, user functions, etc.

If there are no objections, I'd like to commit this in order to get on
with the addition of since and deprecated info in the gtk api docs.

Matthias


Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.64
diff -u -b -B -p -r1.64 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	2 Dec 2002 21:21:49 -0000	1.64
+++ gtkdoc-mkdb.in	2 Dec 2002 23:13:32 -0000
@@ -2569,8 +2569,8 @@ sub ReadTemplateFile {
 		|| $symbol eq "Long_Description"
 		|| $symbol eq "See_Also") {
 		$symbol = $docsfile . ":" . $symbol;
-#		print "Found symbol: $symbol\n";
 	    }
+#	    print "Found symbol: $symbol\n";
 
 	    # Store previous symbol, but remove any trailing blank lines.
 	    if ($current_symbol ne "") {
@@ -2578,6 +2578,28 @@ sub ReadTemplateFile {
 		$SymbolTypes{$current_symbol} = $current_type;
 		$SymbolDocs{$current_symbol} = $symbol_doc;
 		if ($current_param >= 0) {
+		    if ($current_param > 0) {
+			if ($params[$current_param - 1] eq "Deprecated") {
+			    $Deprecated{$current_symbol} = pop (@params);
+			    pop (@params);
+			    $current_param -= 2;
+			}
+		    }
+		    if ($current_param > 0) {
+			if ($params[$current_param - 1] eq "Since") {
+			    $Since{$current_symbol} = pop (@params);
+			    pop (@params);
+			    $current_param -= 2;
+			}
+		    }
+		    # look for deprecated again to support both orders
+		    if ($current_param > 0) {
+			if ($params[$current_param - 1] eq "Deprecated") {
+			    $Deprecated{$current_symbol} = pop (@params);
+			    pop (@params);
+			    $current_param -= 2;
+			}
+		    }
 		    $SymbolParams{$current_symbol} = [ @params ];
 		} else {
 		    # Delete any existing params in case we are overriding a
@@ -2631,6 +2653,27 @@ sub ReadTemplateFile {
 	$SymbolTypes{$current_symbol} = $current_type;
 	$SymbolDocs{$current_symbol} = $symbol_doc;
 	if ($current_param >= 0) {
+	    if ($current_param > 0) {
+		if ($params[$current_param - 1] eq "Deprecated") {
+		    $Deprecated{$current_symbol} = pop (@params);
+		    pop (@params);
+		    $current_param -= 2;
+		}
+	    }
+	    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 "Deprecated") {
+		    $Deprecated{$current_symbol} = pop (@params);
+		    pop (@params);
+		    $current_param -= 2;
+		}
+	    }
 	    $SymbolParams{$current_symbol} = [ @params ];
 	} else {
 	    delete $SymbolParams{$current_symbol};
Index: gtkdoc-mktmpl.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mktmpl.in,v
retrieving revision 1.26
diff -u -b -B -p -r1.26 gtkdoc-mktmpl.in
--- gtkdoc-mktmpl.in	8 Nov 2002 23:43:34 -0000	1.26
+++ gtkdoc-mktmpl.in	2 Dec 2002 23:13:33 -0000
@@ -399,6 +399,8 @@ EOF
 	    $output .= &OutputParam ($symbol, "Returns", $template_exists, 1,
 				     "");
 	}
+	$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
+	$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
         $output .= &OutputOldParams ($symbol);
 	$output .= "\n";
     }
@@ -416,6 +418,8 @@ EOF
 	    }
 	}
 	$output .= &OutputParam ($symbol, "Returns", $template_exists, 0, "");
+	$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
+	$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
 	$output .= &OutputOldParams ($symbol);
 	$output .= "\n";
     }
@@ -428,6 +432,8 @@ EOF
 	    my $field_name = $fields[$i];
 	    $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
 	}
+	$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
+	$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
     }
 
     if ($type eq "ENUM") {
@@ -436,6 +442,8 @@ EOF
 	for my $member (@members) {
 	    $output .= &OutputParam ($symbol, $member, $template_exists, 1, "");
 	}
+	$output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
+	$output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
     }
 
     $output .= "\n";