GNOME.org
 

deprecation docs

Hi,

Following patch adds an argument --deprecated-guards which is a regexp
matching preprocessor symbols that are used to bracket deprecated
stuff in headers.

e.g.
gtkdoc-scan --deprecated-guards='GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED'

It then inserts <DEPRECATED/> in gtk-decl.txt for all deprecated
symbols, and gtkdoc-mkdb outputs a <warning></warning> about
deprecated symbols. Seems like a nice simple solution that
automatically keeps docs in sync with the header files.

I'd still like to have a way to change the <warning></warning> on a
per-symbol basis, but we can always add that later.

Also, I put Emacs magic for cperl at the top of the .in files.

Havoc

Index: gtkdoc-fixxref.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-fixxref.in,v
retrieving revision 1.4
diff -u -u -r1.4 gtkdoc-fixxref.in
--- gtkdoc-fixxref.in	2001/01/23 01:59:37	1.4
+++ gtkdoc-fixxref.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.20
diff -u -u -r1.20 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	2001/01/23 01:59:37	1.20
+++ gtkdoc-mkdb.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
@@ -91,6 +92,7 @@
 my %DeclarationTypes;
 my %DeclarationConditional;
 my %DeclarationOutput;
+my %Deprecated;
 
 # These global hashes store the existing documentation.
 my %SymbolDocs;
@@ -409,6 +411,11 @@
 	$desc .= &CreateValidSGML ($args);
 	$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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -435,6 +442,11 @@
 	$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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -507,6 +519,11 @@
 
     $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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -580,6 +597,11 @@
     my $desc = "<refsect2>\n<title><anchor id=\"$id\">enum $symbol</title>\n";
     $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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -646,6 +668,11 @@
     my $desc = "<refsect2>\n<title><anchor id=\"$id\">union $symbol</title>\n";
     $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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -679,6 +706,11 @@
     my $desc = "<refsect2>\n<title><anchor id=\"$id\">$symbol</title>\n";
     $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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -832,6 +864,12 @@
     }
     $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 (defined ($SymbolDocs{$symbol})) {
 	$desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
     }
@@ -1757,6 +1795,7 @@
     my $declaration_type = "";
     my $declaration_name;
     my $declaration;
+    my $is_deprecated = 0;
     while (<INPUT>) {
 	if (!$declaration_type) {
 	    if (m/^<([^>]+)>/) {
@@ -1768,7 +1807,9 @@
 	} else {
 	    if (m%^<NAME>(.*)</NAME>%) {
 		$declaration_name = $1;
-	    } elsif (m%^</$declaration_type>%) {
+            } elsif (m%^<DEPRECATED/>%) {
+                $is_deprecated = 1;
+            } elsif (m%^</$declaration_type>%) {
 #		print "Found end of declaration: $declaration_name\n";
 		# Check that the declaration has a name
 		if ($declaration_name eq "") {
@@ -1782,6 +1823,7 @@
 		    if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
 			# Ignore it.
 		    } elsif ($declaration_type eq 'FUNCTION') {
+                        $Deprecated{$declaration_name} = $is_deprecated;
 			$Declarations{$declaration_name} = $declaration;
 			$DeclarationTypes{$declaration_name} = $declaration_type;
 		    } elsif ($DeclarationTypes{$declaration_name}
@@ -1789,6 +1831,7 @@
 			# If the existing declaration is empty override it.
 			if ($declaration_type eq 'STRUCT') {
 			    if ($Declarations{$declaration_name} =~ m/^\s*$/) {
+                                $Deprecated{$declaration_name} = $is_deprecated;
 				$Declarations{$declaration_name} = $declaration;
 			    } elsif ($declaration =~ m/^\s*$/) {
 				# Ignore an empty declaration.
@@ -1805,10 +1848,13 @@
 			print "ERROR: $declaration_name has multiple definitions\n";
 		    }
 		} else {
+                    $Deprecated{$declaration_name} = $is_deprecated;
 		    $Declarations{$declaration_name} = $declaration;
 		    $DeclarationTypes{$declaration_name} = $declaration_type;
 		}
+
 		$declaration_type = "";
+                $is_deprecated = 0;
 	    } else {
 		$declaration .= $_;
 	    }
Index: gtkdoc-mktmpl.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mktmpl.in,v
retrieving revision 1.15
diff -u -u -r1.15 gtkdoc-mktmpl.in
--- gtkdoc-mktmpl.in	2001/01/23 01:59:37	1.15
+++ gtkdoc-mktmpl.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
@@ -806,7 +807,10 @@
 	} else {
 	    if (m%^<NAME>(.*)</NAME>%) {
 		$declaration_name = $1;
-	    } elsif (m%^</$declaration_type>%) {
+	    } elsif (m%<DEPRECATED/>%) {
+                # do nothing, just skip the line; we handle this
+                # in mkdb
+            } elsif (m%^</$declaration_type>%) {
 #		print "Found end of declaration: $declaration_name\n";
 		# Check that the declaration has a name
 		if ($declaration_name eq "") {
Index: gtkdoc-scan.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scan.in,v
retrieving revision 1.12
diff -u -u -r1.12 gtkdoc-scan.in
--- gtkdoc-scan.in	2001/01/23 01:59:37	1.12
+++ gtkdoc-scan.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
@@ -49,20 +50,28 @@
 my @SOURCE_DIRS;
 my $IGNORE_HEADERS = "";
 my $PRINT_VERSION;
+# regexp matching cpp symbols which surround deprecated stuff
+# e.g. 'GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED'
+# these are detected if they are used as #if FOO, #ifndef FOO, or #ifdef FOO
+my $DEPRECATED_GUARDS;
 
 my %optctl = (module => \$MODULE,
 	      'source-dir' => \ SOURCE_DIRS,
 	      'ignore-headers' => \$IGNORE_HEADERS,
 	      'output-dir' => \$OUTPUT_DIR,
-	      'version' => \$PRINT_VERSION);
+	      'version' => \$PRINT_VERSION,
+              'deprecated-guards' => \$DEPRECATED_GUARDS);
 GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
-	   "output-dir:s", "version");
+	   "output-dir:s", "version",
+           "deprecated-guards:s");
 
 if ($PRINT_VERSION) {
     print "@VERSION \n";
     exit 0;
 }
 
+$DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope";
+
 $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
 
 if (!-d ${OUTPUT_DIR}) {
@@ -176,6 +185,11 @@
 				#   subclasses, which we remove from the list.
 
     my $file_basename;
+    
+    my $deprecated_conditional_nest = 0;
+
+    my $deprecated = "";
+
     if ($input_file =~ m/^.*[\/\\](.*)\.h$/) {
 	$file_basename = $1;
     } else {
@@ -211,6 +225,32 @@
 	    next;
 	}
 
+        # Keep a count of #if, #ifdef, #ifndef nesting,
+        # and if we enter a deprecation-symbol-bracketed
+        # zone, take note.
+        if (m/^\s*#\s*if\w*\s+(\w+)/) {
+            if ($deprecated_conditional_nest == 0 and $1 =~ /$DEPRECATED_GUARDS/) {
+                 $deprecated_conditional_nest = 1;
+            } elsif ($deprecated_conditional_nest > 0) {
+                 $deprecated_conditional_nest += 1;
+            }
+        } elsif (m/^\s*#\sif/) {
+            if ($deprecated_conditional_nest > 0) {
+                 $deprecated_conditional_nest += 1;
+            }
+        } elsif (m/^\s*#endif/) {
+            if ($deprecated_conditional_nest > 0) {
+                $deprecated_conditional_nest -= 1;
+            }
+        }
+
+        # set global that affects AddSymbolToList
+        if ($deprecated_conditional_nest > 0) {
+            $deprecated = "<DEPRECATED/>\n";
+        } else {
+            $deprecated = "";
+        }
+
 	if (!$in_declaration) {
 	    # Skip top-level comments.
 	    if (s%^\s*/\*%%) {
@@ -284,7 +324,7 @@
 		# will override this.
 #		print "DEBUG: struct typedef: $1\n";
 		&AddSymbolToList (\$list, $1);
-		print DECL "<STRUCT>\n<NAME>$1</NAME>\n</STRUCT>\n";
+		print DECL "<STRUCT>\n<NAME>$1</NAME>\n$deprecated</STRUCT>\n";
 
 	    } elsif (m/^\s*typedef\s+struct\s*{/) {
 		$symbol = "";
@@ -315,7 +355,7 @@
 		if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) {
 #		    print "Found typedef: $_";
 		    &AddSymbolToList (\$list, $3);
-		    print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$_</TYPEDEF>\n";
+		    print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
 		}
 	    } elsif (m/^\s*typedef\s+/) {
 #		print "Skipping typedef: $_";
@@ -328,7 +368,7 @@
 	        s/^\s*([A-Za-z_]+VAR)\b/extern/;
 #		print "Possible extern: $_";
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$_</VARIABLE>\n";
+		print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$_</VARIABLE>\n";
 
 
 	    # FUNCTIONS
@@ -393,7 +433,7 @@
 						# and end of lines.
 		$ret_type =~ s%/\*.*?\*/%%g;	# remove comments in ret type.
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
+		print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
 		$in_declaration = "";
 	    }
 	}
@@ -401,7 +441,7 @@
 	if ($in_declaration eq 'user_function') {
 	    if ($decl =~ s/\).*$//) {
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
+		print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
 		$in_declaration = "";
 	    }
 	}
@@ -409,7 +449,7 @@
 	if ($in_declaration eq 'macro') {
 	    if ($decl !~ m/\\\s*$/) {
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$decl</MACRO>\n";
+		print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n";
 		$in_declaration = "";
 	    }
 	}
@@ -420,7 +460,7 @@
 		    $symbol = $1;
 		}
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$decl</ENUM>\n";
+		print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n";
 		$in_declaration = "";
 	    }
 	}
@@ -442,9 +482,9 @@
 		    &AddSymbolToList (\$list, $symbol);
 
 		    if ($decl =~ m/^\s*typedef\s+struct\s*{/) {
-		      print DECL "<TYPEDEF>\n<NAME>$symbol</NAME>\n$decl</TYPEDEF>\n";
+		      print DECL "<TYPEDEF>\n<NAME>$symbol</NAME>\n$deprecated$decl</TYPEDEF>\n";
 		    } else {
-		      print DECL "<STRUCT>\n<NAME>$symbol</NAME>\n$decl</STRUCT>\n";
+		      print DECL "<STRUCT>\n<NAME>$symbol</NAME>\n$deprecated$decl</STRUCT>\n";
 		    }
 		}
 		$in_declaration = "";
@@ -459,7 +499,7 @@
 	if ($in_declaration eq 'union') {
 	    if ($decl =~ m/\}\s*;\s*$/) {
 		&AddSymbolToList (\$list, $symbol);
-		print DECL "<UNION>\n<NAME>$symbol</NAME>\n$decl</UNION>\n";
+		print DECL "<UNION>\n<NAME>$symbol</NAME>\n$deprecated$decl</UNION>\n";
 		$in_declaration = "";
 	    }
 	}
Index: gtkdoc-scangobj.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scangobj.in,v
retrieving revision 1.9
diff -u -u -r1.9 gtkdoc-scangobj.in
--- gtkdoc-scangobj.in	2001/01/23 01:59:37	1.9
+++ gtkdoc-scangobj.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
Index: gtkdoc-scanobj.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scanobj.in,v
retrieving revision 1.9
diff -u -u -r1.9 gtkdoc-scanobj.in
--- gtkdoc-scanobj.in	2001/01/23 01:59:37	1.9
+++ gtkdoc-scanobj.in	2001/01/25 04:06:38
@@ -1,4 +1,5 @@
 #! PERL@ -w
+# -*- cperl -*-
 #
 # gtk-doc - GTK DocBook documentation generator.
 # Copyright (C) 1998  Damon Chaplin
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]