using blurbs for property documentation

[Matthias Clasen <maclas gmx de>]

I have just attached the following patch to
http://bugzilla.gnome.org/show_bug.cgi?id=74016

Matthias

Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.40
diff -u -b -B -p -r1.40 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	18 Jan 2002 17:24:48 -0000	1.40
+++ gtkdoc-mkdb.in	8 Mar 2002 21:21:13 -0000
@@ -108,7 +108,8 @@ my @ArgObjects;		# The GtkObject which h
 my @ArgNames;		# The Arg name.
 my @ArgTypes;		# The Arg type - gint, GtkArrowType etc.
 my @ArgFlags;		# How the Arg can be used - readable/writable etc.
-
+my @ArgNicks;		# The nickname of the Arg.
+my @ArgBlurbs;          # Docstring of the Arg.
 # These global hashes store declaration info keyed on a symbol name.
 my %Declarations;
 my %DeclarationTypes;
@@ -1506,10 +1507,11 @@ sub GetArgs {
 
 	    $desc .= "<varlistentry><term><anchor id=\"$id\">&quot;<literal>$name</literal>&quot; ($type_output : $flags_string)</term>\n<listitem>\n";
 
+	    my $blurb = $ArgBlurbs[$i];
+	    $desc .= "<para>$blurb</para>\n";
+
 	    if (defined ($SymbolDocs{$symbol})) {
 	        $desc .= &ExpandAbbreviations($SymbolDocs{$symbol});
-	    } else {
-		$desc .= "<para></para>\n";
 	    }
 
 	    $desc .= "</listitem></varlistentry>\n";
@@ -2279,7 +2281,8 @@ sub ReadObjectHierarchy {
 # Function    : ReadArgsFile
 # Description : This reads in an existing file which contains information on
 #		all GTK args. It creates the arrays @ArgObjects, @ArgNames,
-#		@ArgTypes and @ArgFlags containing info on the args.
+#		@ArgTypes, @ArgFlags, @ArgNicks and @ArgBlurbs containing info 
+#               on the args.
 # Arguments   : $file - the file containing the arg information.
 #############################################################################
 
@@ -2291,12 +2294,16 @@ sub ReadArgsFile {
     my $arg_name;
     my $arg_type;
     my $arg_flags;
+    my $arg_nick;
+    my $arg_blurb;
 
     # Reset the signal info.
     @ArgObjects = ();
     @ArgNames = ();
     @ArgTypes = ();
     @ArgFlags = ();
+    @ArgNicks = ();
+    @ArgBlurbs = ();
 
     if (! -f $file) {
 	return;
@@ -2313,6 +2320,8 @@ sub ReadArgsFile {
 		$arg_name = "";
 		$arg_type = "";
 		$arg_flags = "";
+		$arg_nick = "";
+		$arg_blurb = "";
 	    }
 	} else {
 	    if (m/^<NAME>(.*)<\/NAME>/) {
@@ -2328,12 +2337,18 @@ sub ReadArgsFile {
 		$arg_type = $1;
 	    } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
 		$arg_flags = $1;
+	    } elsif (m/^<NICK>(.*)<\/NICK>/) {
+		$arg_nick = $1;
+	    } elsif (m/^<BLURB>(.*)<\/BLURB>/) {
+		$arg_blurb = $1;
 	    } elsif (m%^</ARG>%) {
 #		print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
 		push (@ArgObjects, $arg_object);
 		push (@ArgNames, $arg_name);
 		push (@ArgTypes, $arg_type);
 		push (@ArgFlags, $arg_flags);
+		push (@ArgNicks, $arg_nick);
+		push (@ArgBlurbs, $arg_blurb);
 		$in_arg = 0;
 	    }
 	}
Index: gtkdoc-scangobj.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-scangobj.in,v
retrieving revision 1.20
diff -u -b -B -p -r1.20 gtkdoc-scangobj.in
--- gtkdoc-scangobj.in	23 Jan 2002 23:42:57 -0000	1.20
+++ gtkdoc-scangobj.in	8 Mar 2002 21:21:15 -0000
@@ -773,8 +773,8 @@ output_widget_args (FILE *fp, GType obje
 	*pos++ = 'X';
       *pos = 0;
 
-      fprintf (fp, "<ARG>\\n<NAME>%s::%s</NAME>\\n<TYPE>%s</TYPE>\\n<FLAGS>%s</FLAGS>\\n</ARG>\\n\\n",
-	       object_class_name, spec->name, g_type_name (spec->value_type), flags);
+      fprintf (fp, "<ARG>\\n<NAME>%s::%s</NAME>\\n<TYPE>%s</TYPE>\\n<FLAGS>%s</FLAGS>\\n<NICK>%s</NICK>\\n<BLURB>%s</BLURB>\\n</ARG>\\n\\n",
+	       object_class_name, g_param_spec_get_name (spec), g_type_name (spec->value_type), flags, g_param_spec_get_nick (spec), g_param_spec_get_blurb (spec));
     }
 
   g_free (properties);