gtk-doc r607 - in trunk: . doc tests/annotations/docs tests/annotations/src tests/bugs/docs tests/gobject/docs
- From: stefkost svn gnome org
- To: svn-commits-list gnome org
- Subject: gtk-doc r607 - in trunk: . doc tests/annotations/docs tests/annotations/src tests/bugs/docs tests/gobject/docs
- Date: Mon, 13 Oct 2008 16:20:41 +0000 (UTC)
Author: stefkost
Date: Mon Oct 13 16:20:41 2008
New Revision: 607
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=607&view=rev
Log:
* TODO:
planning.
* doc/gtkdoc.dot:
Document workflow
* devhelp2.xsl:
Add support for enums/flags in devhelp index.
* gtkdoc-mkdb.in:
Support annotations. Fix missing roles.
* tests/annotations/docs/tester-docs.xml:
* tests/annotations/src/tester.c:
* tests/annotations/src/tester.h:
* tests/bugs/docs/tester-sections.txt:
* tests/gobject/docs/tester-docs.xml:
Update new syntax.
Added:
trunk/doc/gtkdoc.dot
Modified:
trunk/ChangeLog
trunk/TODO
trunk/devhelp2.xsl
trunk/gtkdoc-mkdb.in
trunk/tests/annotations/docs/tester-docs.xml
trunk/tests/annotations/src/tester.c
trunk/tests/annotations/src/tester.h
trunk/tests/bugs/docs/tester-sections.txt
trunk/tests/gobject/docs/tester-docs.xml
Modified: trunk/TODO
==============================================================================
--- trunk/TODO (original)
+++ trunk/TODO Mon Oct 13 16:20:41 2008
@@ -118,3 +118,21 @@
- 'dummy-docs' check if symbol docs are very short and repeat mainly words
from the symbol.
+= GIR =
+== scanning ==
+* ideas
+ 1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files
+ 2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
+* perl and xml
+ * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
+== handling the annotations ==
+* figure out how to install default glossary
+== output ==
+* add gtkdoc-mk??? to generate docbook xml templates for binding docs
+* have c-comments there as comments
+* when updating, mark sections that have changed
+== installation ==
+* need to install each book with a prefix
+* would be good to have a language attribute in book tag to allow filter by language
+* look at /usr/share/gtk-doc/html/pygobject/index.html
+
Modified: trunk/devhelp2.xsl
==============================================================================
--- trunk/devhelp2.xsl (original)
+++ trunk/devhelp2.xsl Mon Oct 13 16:20:41 2008
@@ -55,6 +55,8 @@
<functions>
<xsl:apply-templates select="//refsect2"
mode="generate.devhelp2.index.mode"/>
+ <xsl:apply-templates select="//refsect2/variablelist[ role='enum']/varlistentry"
+ mode="generate.devhelp2.index.mode"/>
</functions>
</book>
</xsl:template>
@@ -86,7 +88,7 @@
</xsl:template>
<xsl:template match="*" mode="generate.devhelp2.index.mode">
- <xsl:variable name="title" select="title"/>
+ <xsl:variable name="title" select="title|term/literal"/>
<xsl:variable name="anchor" select="title/anchor"/>
<xsl:variable name="type" select="@role"/>
<xsl:variable name="condition" select="@condition"/>
Added: trunk/doc/gtkdoc.dot
==============================================================================
--- (empty file)
+++ trunk/doc/gtkdoc.dot Mon Oct 13 16:20:41 2008
@@ -0,0 +1,78 @@
+/* files and tools in gtk-doc workflow
+ * dot -Tpng gtkdoc.dot -ogtkdoc.png
+ */
+
+digraph gtkdoc {
+ /* graph attributes */
+ /*rankdir=BT;*/
+
+ /* default node attributes */
+ node [ shape=box];
+
+ /* tools nodes */
+ gtkdoc_scan [label="gtkdoc-scan",shape="ellipse" ];
+ gtkdoc_scangobj [label="gtkdoc-scangobj",shape="ellipse" ];
+ gtkdoc_mkdb [label="gtkdoc-mkdb",shape="ellipse" ];
+ gtkdoc_mkhtml [label="gtkdoc-mkhtml",shape="ellipse" ];
+ gtkdoc_fixxref [label="gtkdoc-fixxref",shape="ellipse" ];
+ gtkdoc_rebase [label="gtkdoc-rebase",shape="ellipse" ];
+ gtkdoc_check [label="gtkdoc-check",shape="ellipse" ];
+
+ /* file nodes */
+ sources [label="source code"];
+ binary [label="compiled binary"];
+ xml [label="docbook xml"];
+ html [label="html"];
+ module_decl_list [label="*-decl-list.txt" ];
+ module_decl [label="*-decl.txt" ];
+ module_types [label="*.types" ];
+ module_sections [label="*-section.txt" ];
+ module_signals [label="*.signals" ];
+ module_hierarchy [label="*.hierarchy" ];
+ module_interfaces [label="*.interfaces" ];
+ module_prerequisites [label="*.prerequisites" ];
+ module_args [label="*.args" ];
+ module_undeclared [label="*-undeclared.txt" ];
+ module_undocumented [label="*-undocumented.txt" ];
+ module_unused [label="*-unused.txt" ];
+
+ /* tool invokation */
+ gtkdoc_scan -> gtkdoc_scangobj -> gtkdoc_mkdb -> gtkdoc_mkhtml -> gtkdoc_fixxref -> gtkdoc_rebase -> gtkdoc_check [style="dotted"];
+
+ /* file usage */
+ sources -> gtkdoc_scan;
+ gtkdoc_scan -> module_sections [label="--rebuild-sections", style="dashed"];
+ gtkdoc_scan -> module_types [label="--rebuild-types", style="dashed"];
+ gtkdoc_scan -> module_decl;
+ gtkdoc_scan -> module_decl_list;
+
+ binary -> gtkdoc_scangobj;
+ module_types -> gtkdoc_scangobj;
+ gtkdoc_scangobj -> module_signals;
+ gtkdoc_scangobj -> module_hierarchy;
+ gtkdoc_scangobj -> module_interfaces;
+ gtkdoc_scangobj -> module_prerequisites;
+ gtkdoc_scangobj -> module_args;
+
+ module_sections -> gtkdoc_mkdb;
+ module_decl -> gtkdoc_mkdb;
+ module_signals -> gtkdoc_mkdb;
+ module_args -> gtkdoc_mkdb;
+ module_hierarchy -> gtkdoc_mkdb;
+ module_interfaces -> gtkdoc_mkdb;
+ module_prerequisites -> gtkdoc_mkdb;
+ gtkdoc_mkdb -> xml;
+ gtkdoc_mkdb -> module_undeclared;
+ gtkdoc_mkdb -> module_undocumented;
+ gtkdoc_mkdb -> module_unused;
+
+ xml -> gtkdoc_mkhtml -> html;
+
+ html -> gtkdoc_fixxref -> html;
+ html -> gtkdoc_rebase -> html;
+
+ module_undeclared -> gtkdoc_check;
+ module_undocumented -> gtkdoc_check;
+ module_unused -> gtkdoc_check;
+}
+
Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in (original)
+++ trunk/gtkdoc-mkdb.in Mon Oct 13 16:20:41 2008
@@ -275,6 +275,7 @@
my $RETURN_TYPE_FIELD_WIDTH = 20;
my $SYMBOL_FIELD_WIDTH = 36;
my $SIGNAL_FIELD_WIDTH = 16;
+my $PARAM_FIELD_COUNT = 2;
&ReadKnownSymbols ("$ROOT_DIR/$MODULE-sections.txt");
&ReadSignalsFile ($SIGNALS_FILE);
@@ -1237,7 +1238,7 @@
my $found = 0;
if (defined $params) {
- for (my $i = 1; $i <= $#$params; $i += 2) {
+ for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) {
if ($params->[$i] =~ /\S/) {
$found = 1;
last;
@@ -1308,7 +1309,7 @@
my $found = 0;
if (defined $params) {
- for (my $i = 1; $i <= $#$params; $i += 2) {
+ for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) {
if ($params->[$i] =~ /\S/) {
$found = 1;
last;
@@ -1644,17 +1645,36 @@
my $params = $SymbolParams{$symbol};
my $params_desc = "";
my $j;
- for ($j = 0; $j <= $#$params; $j += 2) {
+ for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) {
my $param_name = $$params[$j];
- my $param = $$params[$j + 1];
+ my $param_desc = $$params[$j + 1];
+ my $param_annotations = "";
+
+ if ($param_desc =~ m%\s*\((.*)\):%) {
+ my @annotations;
+ my $annotation;
+ my $annotation_extra = "";
+ $param_desc = $';
+ @annotations = split(/\)\s*\(/,$1);
+ foreach $annotation (@annotations) {
+ if ($annotation =~ m%(.*)\s+(.*)%) {
+ $annotation = $1;
+ $annotation_extra = " $2";
+ }
+ $param_annotations .= "<acronym>$annotation</acronym>$annotation_extra. ";
+ }
+ chomp($param_desc);
+ $param_desc =~ m/^(.*)\.*\s*$/;
+ $param_desc = "$1. ";
+ }
+ $param_desc = &ExpandAbbreviations($symbol, $param_desc);
if ($param_name eq "Returns") {
- $returns = &ExpandAbbreviations($symbol, $param);
+ $returns = "$param_desc$param_annotations";
} else {
if ($param_name eq "Varargs") {
$param_name = "...";
}
- $param = &ExpandAbbreviations($symbol, $param);
- $params_desc .= "<varlistentry><term><parameter>$param_name</parameter> :</term>\n<listitem><simpara>$param</simpara></listitem></varlistentry>\n";
+ $params_desc .= "<varlistentry><term><parameter>$param_name</parameter> :</term>\n<listitem><simpara>$param_desc$param_annotations</simpara></listitem></varlistentry>\n";
}
}
@@ -2724,7 +2744,7 @@
my $pad = ' ' x (46 - length($name));
$synop .= " "<link linkend=\"$id\">$name</link>"$pad ";
- $desc .= "<refsect2 id=\"$id\"><title>The <literal>"$name"</literal> signal</title>\n";
+ $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>"$name"</literal> signal</title>\n";
$desc .= MakeIndexterms($symbol, $id);
$desc .= "<programlisting>";
@@ -2755,7 +2775,7 @@
$type = $1;
$pointer = $2;
if (defined($sourceparams)) {
- $name = $$sourceparams[2 * $j];
+ $name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
}
else {
$name = $3;
@@ -2964,7 +2984,7 @@
my $pad2 = " " x (20 - length ($type));
my $arg_synop = " "<link linkend=\"$id\">$name</link>"$pad1 $type_output $pad2 : $flags_string\n";
- my $arg_desc = "<refsect2 id=\"$id\"><title>The <literal>"$name"</literal> $kind</title>\n";
+ my $arg_desc = "<refsect2 id=\"$id\" role=\"property\"><title>The <literal>"$name"</literal> $kind</title>\n";
$arg_desc .= MakeIndexterms($symbol, $id);
$arg_desc .= "<programlisting> "$name"$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
$arg_desc .= $blurb;
@@ -3138,7 +3158,7 @@
# Convert special SGML characters
$description = &ConvertSGMLChars ($symbol, $description);
my $k;
- for ($k = 1; $k <= $#params; $k += 2) {
+ for ($k = 1; $k <= $#params; $k += $PARAM_FIELD_COUNT) {
$params[$k] = &ConvertSGMLChars ($symbol, $params[$k]);
}
@@ -3149,7 +3169,7 @@
#print "SECTION DOCS found in source for : '$real_symbol'\n";
$ignore_broken_returns = 1;
- for ($k = 0; $k <= $#params; $k += 2) {
+ for ($k = 0; $k <= $#params; $k += $PARAM_FIELD_COUNT) {
#print " '".$params[$k]."'\n";
$params[$k] = "\L$params[$k]";
undef $key;
@@ -3437,6 +3457,7 @@
# Look for a parameter name.
if (m%^\s*@(\S+)\s*:%) {
my $param_name = $1;
+ my $param_desc = $';
#print "Found parameter: $param_name\n";
# Allow '...' as the Varargs parameter.
if ($param_name eq "...") {
@@ -3447,8 +3468,8 @@
$ignore_broken_returns = 1;
}
push (@params, $param_name);
- push (@params, $');
- $current_param += 2;
+ push (@params, $param_desc);
+ $current_param += $PARAM_FIELD_COUNT;
next;
}
@@ -3717,7 +3738,7 @@
my $params = $SourceSymbolParams{$symbol};
my $j;
#print "Merge needed for $symbol, tmpl_params: ",$#$tmpl_params,", source_params: ",$#$params," \n";
- for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
+ for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
my $tmpl_param_name = $$tmpl_params[$j];
# Allow '...' as the Varargs parameter.
@@ -3728,7 +3749,7 @@
# Try to find the param in the source comment documentation.
my $found = 0;
my $k;
- for ($k = 0; $k <= $#$params; $k += 2) {
+ for ($k = 0; $k <= $#$params; $k += $PARAM_FIELD_COUNT) {
my $param_name = $$params[$k];
my $param_desc = $$params[$k + 1];
@@ -3756,7 +3777,7 @@
# Now we output a warning if parameters have been described which
# do not exist.
- for ($j = 0; $j <= $#$params; $j += 2) {
+ for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) {
my $param_name = $$params[$j];
if ($param_name) {
# the template builder cannot detect if a macro returns
@@ -3807,7 +3828,7 @@
#print "Check param docs for $symbol, tmpl_params: ",$#$tmpl_params,"\n";
my $j;
- for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
+ for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
# Output a warning if the parameter is empty and
# remember for stats.
my $tmpl_param_name = $$tmpl_params[$j];
@@ -4183,6 +4204,7 @@
# Check if param found. Need to handle "..." and "format...".
if (s/^\@([\w\.]+):\040?//) {
my $param_name = $1;
+ my $param_desc = $_;
# Allow variations of 'Returns'
if ($param_name =~ m/^[Rr]eturns?$/) {
$param_name = "Returns";
@@ -4205,8 +4227,8 @@
$StabilityLevel{$current_symbol} = $_;
} else {
push (@params, $param_name);
- push (@params, $_);
- $current_param += 2;
+ push (@params, $param_desc);
+ $current_param += $PARAM_FIELD_COUNT;
}
} else {
# strip trailing whitespaces and blank lines
Modified: trunk/tests/annotations/docs/tester-docs.xml
==============================================================================
--- trunk/tests/annotations/docs/tester-docs.xml (original)
+++ trunk/tests/annotations/docs/tester-docs.xml Mon Oct 13 16:20:41 2008
@@ -28,5 +28,32 @@
<!--index id="api-index-0-9" role="0.9">
<title>Index of new API in 0.9</title>
</index-->
+
+ <glossary>
+ <glossdiv id="glossary-A"><title>A</title>
+ <glossentry>
+ <glossterm><anchor id="glossterm-array"/>array</glossterm>
+ <glossdef>
+ <para>Points to an array of items.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+ <glossdiv id="glossary-C"><title>C</title>
+ <glossentry>
+ <glossterm><anchor id="glossterm-caller-owns"/>caller-owns</glossterm>
+ <glossdef>
+ <para>When the code is done, free-function must be called.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+ <glossdiv id="glossary-N"><title>N</title>
+ <glossentry>
+ <glossterm><anchor id="glossterm-null-ok"/>null-ok</glossterm>
+ <glossdef>
+ <para>NULL is ok, both for passing and for returning.</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+ </glossary>
</book>
Modified: trunk/tests/annotations/src/tester.c
==============================================================================
--- trunk/tests/annotations/src/tester.c (original)
+++ trunk/tests/annotations/src/tester.c Mon Oct 13 16:20:41 2008
@@ -14,7 +14,7 @@
* annotation_array_length:
* @store: a #GtkListStore
* @n_columns: number of columns
- * @types: [array,length=n_columns]: list of types
+ * @types: (array length=n_columns): list of types
*
* Document parameter relation for array length.
*/
@@ -29,13 +29,17 @@
/**
* annotation_nullable:
* @uri: a uri
- * @label: [allow-none]: an optional string
+ * @label: (null-ok): an optional string
*
* Document optional parameters.
+ *
+ * Returns: (caller-owns) (null-ok): Returns stuff which you have to free after use
*/
-void
+gchar *
annotation_nullable (const gchar *uri,
const gchar *label)
{
+ return NULL;
}
+
Modified: trunk/tests/annotations/src/tester.h
==============================================================================
--- trunk/tests/annotations/src/tester.h (original)
+++ trunk/tests/annotations/src/tester.h Mon Oct 13 16:20:41 2008
@@ -6,7 +6,7 @@
extern void annotation_array_length (GObject *list, gint n_columns, GType *types);
-extern void annotation_nullable (const gchar *uri, const gchar *label);
+extern gchar * annotation_nullable (const gchar *uri, const gchar *label);
#endif // GTKDOC_TESTER_H
Modified: trunk/tests/bugs/docs/tester-sections.txt
==============================================================================
--- trunk/tests/bugs/docs/tester-sections.txt (original)
+++ trunk/tests/bugs/docs/tester-sections.txt Mon Oct 13 16:20:41 2008
@@ -23,5 +23,6 @@
bug_554833
<SUBSECTION Standard>
<SUBSECTION Private>
+bug_554833_new
</SECTION>
Modified: trunk/tests/gobject/docs/tester-docs.xml
==============================================================================
--- trunk/tests/gobject/docs/tester-docs.xml (original)
+++ trunk/tests/gobject/docs/tester-docs.xml Mon Oct 13 16:20:41 2008
@@ -1,11 +1,10 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
-<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
-<!ENTITY GtkdocIFace SYSTEM "xml/iface.xml">
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
-<book id="index">
-<!--book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"-->
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
<bookinfo>
<title>tester Reference Manual</title>
<releaseinfo>
@@ -26,8 +25,7 @@
<chapter id="main-api">
<title>Tests</title>
<xi:include href="xml/object.xml"/>
- <!--xi:include href="xml/iface.xml"/-->
- &GtkdocIFace;
+ <xi:include href="xml/iface.xml"/>
</chapter>
<chapter id="object-tree">
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
