gtk-doc r682 - in trunk: . help/manual/C tests/gobject/src



Author: stefkost
Date: Sat Feb 21 13:12:06 2009
New Revision: 682
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=682&view=rev

Log:
	* gtkdoc-mkdb.in:
	* help/manual/C/gtk-doc-manual.xml:
	* tests/gobject/src/gobject.c:
	  Allow linking to struct members. Update docs. Fixes #565126.



Modified:
   trunk/ChangeLog
   trunk/gtkdoc-mkdb.in
   trunk/help/manual/C/gtk-doc-manual.xml
   trunk/tests/gobject/src/gobject.c

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Sat Feb 21 13:12:06 2009
@@ -1362,7 +1362,7 @@
     my @fields = ParseStructDeclaration($declaration, !$default_to_public,
 					0, \&MakeXRef,
 					sub {
-					    "<structfield>$_[0]</structfield>";
+					    "<structfield id=\"$id.$_[0]\">$_[0]</structfield>";
 					});
     my $params = $SymbolParams{$symbol};
 
@@ -2170,6 +2170,12 @@
 #############################################################################
 # Function    : CreateValidSGMLID
 # Description : Creates a valid SGML 'id' from the given string.
+#               According to http://www.w3.org/TR/html4/types.html#type-id
+#                 "ID and NAME tokens must begin with a letter ([A-Za-z]) and
+#                  may be followed by any number of letters, digits ([0-9]),
+#                  hyphens ("-"), underscores ("_"), colons (":"), and
+#                  periods (".")."
+#
 #		NOTE: SGML ids are case-insensitive, so we have a few special
 #		      cases to avoid clashes of ids.
 # Arguments   : $id - the string to be converted into a valid SGML id.
@@ -2182,7 +2188,7 @@
     if ($id eq "_") { return "gettext-macro"; }
 
     $id =~ s/[_ ]/-/g;
-    $id =~ s/[,\.]//g;
+    $id =~ s/[,;]//g;
     $id =~ s/^-*//;
     $id =~ s/::/-/g;
     $id =~ s/:/--/g;
@@ -2347,19 +2353,16 @@
     $text =~ s/(\w+)\s*\(\)/&MakeXRef($1, &tagify($1 . "()", "function"));/eg;
 
     # Convert '@param', but not '\ param'.
-    #$text =~ s/\@(\w+((\.|->)\w+)*)/<parameter>$1<\/parameter>/g;
     $text =~ s/(\A|[^\\])\@(\w+((\.|->)\w+)*)/$1<parameter>$2<\/parameter>/g;
     $text =~ s/\\\@/\@/g;
 
     # Convert '%constant', but not '\%constant'.
     # Also allow negative numbers, e.g. %-1.
-    #$text =~ s/\%(-?\w+)/&MakeXRef($1, &tagify($1, "literal"));/eg;
     $text =~ s/(\A|[^\\])\%(-?\w+)/$1.&MakeXRef($2, &tagify($2, "literal"));/eg;
     $text =~ s/\\\%/\%/g;
 
     # Convert '#symbol', but not '\#symbol'.
-    #$text =~ s/#([\w\-:]+)/&MakeHashXRef($1, "type");/eg;
-    $text =~ s/(\A|[^\\])#([\w\-:]+)/$1.&MakeHashXRef($2, "type");/eg;
+    $text =~ s/(\A|[^\\])#([\w\-:\.]+)/$1.&MakeHashXRef($2, "type");/eg;
     $text =~ s/\\#/#/g;
     
     # Expand urls
@@ -2414,7 +2417,7 @@
     if ($tag ne "") {
       $text = tagify ($text, $tag);
     }
-
+    
     return &MakeXRef($symbol, $text);
 }
 

Modified: trunk/help/manual/C/gtk-doc-manual.xml
==============================================================================
--- trunk/help/manual/C/gtk-doc-manual.xml	(original)
+++ trunk/help/manual/C/gtk-doc-manual.xml	Sat Feb 21 13:12:06 2009
@@ -46,7 +46,7 @@
       <address><email>gtk-doc-list gnome org</email></address>
     </publisher>
     <copyright>
-      <year>2000, 2005, 2007-2008</year>
+      <year>2000, 2005, 2007-2009</year>
       <holder>Dan Mueth and Chris Lyttle and Stefan Kost</holder>
     </copyright>
 
@@ -597,10 +597,11 @@
         The 'documentation' block is also different for each symbol type. Symbol
         types that get parameters such as functions or macros have the parameter
         description first followed by a blank line (just a '*').
-        Afterwards follows the detailed description. All lines just containing a
-        ' * ' (blank-asterisk-blank) are converted to paragraph breaks.
-        If you don't want a break (e.g. in preformatted example listings) add
-        another space at the end of line.
+        Afterwards follows the detailed description. All lines (outside program-
+        listings and CDATA sections) just containing a ' *' (blank-asterisk) are
+        converted to paragraph breaks.
+        If you don't want a paragraph break, change that into ' *  '
+        (blank-asterisk-blank-blank).
       </para>
 
       <para>
@@ -640,6 +641,11 @@
               Use #Object:property to refer to a GObject property
             </para>
           </listitem>
+          <listitem>
+            <para>
+              Use #Struct.field to refer to a field inside a structure.
+            </para>
+          </listitem>
         </itemizedlist>
       </para>
 
@@ -649,7 +655,7 @@
 	  in your documentation without gtk-doc changing them you can use the
 	  XML entities
 	  "&amp;lpar;", "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and
-	  "&amp;num;" respectively.
+	  "&amp;num;" respectively or escape them with a backslash '\'.
 	</para>
       </tip>
 

Modified: trunk/tests/gobject/src/gobject.c
==============================================================================
--- trunk/tests/gobject/src/gobject.c	(original)
+++ trunk/tests/gobject/src/gobject.c	Sat Feb 21 13:12:06 2009
@@ -7,7 +7,7 @@
  * We can link to the #GtkdocObject:otest property and the #GtkdocObject::otest
  * signal.
  *
- * When subclassing it is useful to override the #GtkdocObjectClass.test()
+ * When subclassing it is useful to override the #GtkdocObjectClass.test
  * method.
  *
  * A new instance can be created using the gtkdoc_object_new() function. The



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]