Commit a737daa1 authored by Dieter Verfaillie's avatar Dieter Verfaillie Committed by Colin Walters

docs: fix up reference docs a bit

      - require GTK-Doc 1.19
      - remove sgml mode
      - automatically generate gi.types (needs GTK-Doc 1.19)
      - fix https://bugzilla.gnome.org/show_bug.cgi?id=700025
[WIP] - rearange sections a bit
[WIP] - add gi-building, gi-programming sections
[WIP] - mark missing docs with TODO, which is only marginaly
        better than nothing but at least can be grepped :)

https://bugzilla.gnome.org/show_bug.cgi?id=571648
parent 3c01854f
......@@ -118,11 +118,17 @@ yelp.js
#GTK-Doc output
docs/reference/html
docs/reference/xml
docs/reference/*.bak
docs/reference/gtkdoc-check.log
docs/reference/gtkdoc-check.test
docs/reference/gtkdoc-check.trs
docs/reference/test-suite.log
docs/reference/gi.args
docs/reference/gi.hierarchy
docs/reference/gi.interfaces
docs/reference/gi.prerequisites
docs/reference/gi.signals
docs/reference/gi.types
docs/reference/gi-decl.txt
docs/reference/gi-decl-list.txt
docs/reference/gi-undeclared.txt
......
EXTRA_DIST += \
girepository/docs.c
girepodir = $(includedir)/gobject-introspection-1.0/
girepo_HEADERS = \
girepository/giarginfo.h \
......
......@@ -16,7 +16,7 @@ EXTRA_DIST =
CLEANFILES =
EOF
else
gtkdocize || exit $?
gtkdocize --flavour no-tmpl || exit $?
fi
AUTORECONF=`which autoreconf`
......
......@@ -22,6 +22,10 @@ AM_MAINTAINER_MODE([enable])
AM_SILENT_RULES([yes])
# Used in docs/reference/version.xml
GI_VERSION=gi_version
AC_SUBST(GI_VERSION)
# Check for Win32
AC_CANONICAL_HOST
case "$host" in
......@@ -229,7 +233,7 @@ GIREPO_CFLAGS="$GIREPO_CFLAGS $GCOV_CFLAGS"
# gtkdocize greps for ^GTK_DOC_CHECK and parses it, so you need to have
# it on it's own line.
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.15], [--flavour no-tmpl])
GTK_DOC_CHECK([1.19], [--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC],[false])
])
......@@ -319,6 +323,7 @@ tests/repository/Makefile
tests/warn/Makefile
docs/Makefile
docs/reference/Makefile
docs/reference/version.xml
gobject-introspection-1.0.pc
gobject-introspection-no-export-1.0.pc
config.h.win32
......
AUTOMAKE_OPTIONS = 1.6
# The name of the module.
# The name of the module, e.g. 'glib'.
DOC_MODULE=gi
# The top-level SGML file.
DOC_MAIN_SGML_FILE=gi-docs.sgml
# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
#DOC_MODULE_VERSION=2
# The directory containing the source code. Relative to $(srcdir)
# The top-level XML file (SGML in the past). You can change this if you want to.
DOC_MAIN_SGML_FILE=gi-docs.xml
# Directories containing the source code.
# gtk-doc will search all .c and .h files beneath these paths
# for inline comments documenting functions and macros.
# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
DOC_SOURCE_DIR=$(top_srcdir)/girepository
# Extra options to supply to gtkdoc-scan
SCAN_OPTIONS=
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g --ignore-files=cmph
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS=--rebuild-types
# Used for dependencies
HFILE_GLOB=$(top_srcdir)/girepository/*.h
CFILE_GLOB=$(top_srcdir)/girepository/*.c
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
MKDB_OPTIONS=--xml-mode --output-format=xml --name-space=g --ignore-files=cmph
# Headers to ignore
IGNORE_HFILES= \
girnode.h \
ginfo.h \
girparser.h \
girwriter.h \
girmodule.h
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS=
AM_CPPFLAGS=$(GIREPO_CFLAGS) -I$(top_srcdir)
GTKDOC_LIBS = $(GIREPO_LIBS) $(top_builddir)/libgirepository-1.0.la $(top_builddir)/libgirepository-internals.la
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
content_files = \
gi-gir-reference.xml \
gi-gir.sgml \
gi-overview.xml \
gi-struct-hierarchy.xml
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(top_srcdir)/girepository/*.h
CFILE_GLOB=$(top_srcdir)/girepository/*.c
HTML_IMAGES = \
# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
EXTRA_HFILES=
# Header files or dirs to ignore when scanning. Use base file/dir names
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
IGNORE_HFILES= \
cmph \
girnode.h \
girparser.h \
girwriter.h \
girmodule.h \
girepository-private.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES= \
$(srcdir)/images/overview.png
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files= \
overview-building.xml \
overview-programming.xml \
gi-gir-reference.xml \
gi-struct-hierarchy.xml \
version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
#
# Set to $(content_files) for simplicity, so we can always
# simply <xi:include href="xml/whatever.xml"/>, even for manually
# written .xml files...
expand_content_files=$(content_files)
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
GTKDOC_CFLAGS= \
-I$(top_srcdir) \
$(GIREPO_CFLAGS)
GTKDOC_LIBS= \
$(top_builddir)/libgirepository-1.0.la \
$(top_builddir)/libgirepository-internals.la \
$(GIREPO_LIBS)
# include common portion ...
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
include $(top_srcdir)/gtk-doc.make
# Other files to distribute
EXTRA_DIST += version.xml.in
gtk-docs-clean:
rm -fr html tmpl xml
clean-local: gtk-docs-clean
########################################################################
dist-hook-local: $(BUILT_EXTRA_DIST)
files='$(BUILT_EXTRA_DIST)'; \
for f in $$files; do \
if test -f $$f; then d=.; else d=$(srcdir); fi; \
cp $$d/$$f $(distdir) || exit 1; done
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
#DISTCLEANFILES +=
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
# Comment this out if you want 'make check' to test you doc status
# and run some sanity checks
## Note: Uncoment this when we start depending on GTK-Doc 1.20
## which solves https://bugzilla.gnome.org/show_bug.cgi?id=701638
##TESTS = $(GTKDOC_CHECK)
endif
gi-docs-clean: clean
cd $(srcdir) && rm -rf xml html
<?xml version="1.0" encoding="utf-8" ?>
<!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 version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GObject Introspection Reference Manual</title>
</bookinfo>
<chapter id="glib">
<title>GObject-Introspection Overview</title>
<para>
Bla bla bla bla bla
</para>
<xi:include href="gi-overview.xml"/>
<!--
&gi-building;
-->
</chapter>
<!--
<chapter id="tools">
<title>GObject Introspection Tools</title>
&g-ir-scanner;
&g-ir-compiler;
&g-ir-generator;
</chapter>
-->
<part id="girepository">
<chapter id="gi-libgirepository">
<title>GIRepository</title>
<xi:include href="xml/girepository.xml"/>
</chapter>
<chapter id="gi-ffi">
<title>GIR Foreign functions interface</title>
<xi:include href="xml/girffi.xml"/>
</chapter>
<chapter id="gi-repository-structs">
<title>GIRepository structs</title>
<xi:include href="gi-struct-hierarchy.xml"/>
<xi:include href="xml/gibaseinfo.xml"/>
<xi:include href="xml/gifunctioninfo.xml"/>
<xi:include href="xml/gicallableinfo.xml"/>
<xi:include href="xml/giarginfo.xml"/>
<xi:include href="xml/gitypeinfo.xml"/>
<xi:include href="xml/gistructinfo.xml"/>
<xi:include href="xml/giunioninfo.xml"/>
<xi:include href="xml/gifieldinfo.xml"/>
<xi:include href="xml/gipropertyinfo.xml"/>
<xi:include href="xml/givfuncinfo.xml"/>
<xi:include href="xml/gisignalinfo.xml"/>
<xi:include href="xml/gienuminfo.xml"/>
<xi:include href="xml/giregisteredtypeinfo.xml"/>
<xi:include href="xml/giobjectinfo.xml"/>
<xi:include href="xml/giinterfaceinfo.xml"/>
<xi:include href="xml/giconstantinfo.xml"/>
<xi:include href="xml/gierrordomaininfo.xml"/>
</chapter>
</part>
<part id="gi-gir">
<title>GIR markup format</title>
<xi:include href="gi-gir-reference.xml" />
<!--
&gi-gir-creating;
&gi-gir-parsing;
&gi-gir-verifying;
-->
</part>
<chapter id="gi-typelib">
<title>Typelib binary format</title>
<xi:include href="xml/gtypelib.xml" />
</chapter>
<xi:include href="xml/annotation-glossary.xml" />
</book>
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "xml/version.xml">
]>
<book id="index" lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>GObject Introspection Reference Manual</title>
<bookinfo>
<title>GObject Introspection Reference Manual</title>
<releaseinfo>
This document is for GObject Introspection version &version;.
The latest version of this documentation can be found on-line at
<ulink type="http" url="http://developer.gnome.org/gi/unstable/">http://developer.gnome.org/gi/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<part id="overview">
<title>GObject-Introspection Overview</title>
<para>
GObject-Introspection is striving to provide a middleware layer between
(GObject based) C libraries and language bindings. The primary goal of
this project is to minimize duplicated effort in language binding
projects by providing shared metadata files on bound C libraries.
Language bindings can read these metadata files at runtime to learn
how to interface with a bound C library.
</para>
<xi:include href="xml/overview-building.xml"/>
<xi:include href="xml/overview-programming.xml"/>
<!-- <chapter>
<title>Introduction</title>
<para>
Metadata provided by GObject-Introspection is represented by a
number of structures:
<synopsis>
* <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
* <link linkend="gi-GICallableInfo">GICallableInfo</link>
* <link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
* <link linkend="gi-GISignalInfo">GISignalInfo</link>
* <link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
* <link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
* <link linkend="gi-GIEnumInfo">GIEnumInfo</link>
* <link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
* <link linkend="gi-GIObjectInfo">GIObjectInfo</link>
* <link linkend="gi-GIStructInfo">GIStructInfo</link>
* <link linkend="gi-GIUnionInfo">GIUnionInfo</link>
* <link linkend="gi-GIArgInfo">GIArgInfo</link>
* <link linkend="gi-GIConstantInfo">GIConstantInfo</link>
* <link linkend="gi-GIFieldInfo">GIFieldInfo</link>
* <link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
* <link linkend="gi-GITypeInfo">GITypeInfo</link>
</synopsis>
</para>
</chapter> -->
<!--
<chapter id="tools">
<title>GObject Introspection Tools</title>
&g-ir-scanner;
&g-ir-compiler;
&g-ir-generator;
</chapter>
-->
<para>
The GObject-Introspection package contains of a few different parts:
<itemizedlist>
<listitem>
<para>The GIR XML format - an XML format describing the exported C API including documentation</para>
</listitem>
<listitem>
<para>The GTypelib format - a binary format optimized for fast disk access and low memory usage</para>
</listitem>
<listitem>
<para>g-ir-scanner - parses C source code and gtk-doc comments and generates GIR XML files</para>
</listitem>
<listitem>
<para>g-ir-compiler - compiles GIR XML files into typelibs</para>
</listitem>
<listitem>
<para>libgirepository - library to access typelib from C</para>
</listitem>
</itemizedlist>
</para>
<para>The following illustration shows how the different components fit together:</para>
<inlinegraphic fileref="overview.png" format="PNG"></inlinegraphic>
</part>
<part id="gi">
<title>API Reference</title>
<chapter>
<title>GIRepository</title>
<xi:include href="xml/girepository.xml"/>
<xi:include href="xml/gi-struct-hierarchy.xml"/>
<xi:include href="xml/gicommontypes.xml"/>
<xi:include href="xml/gibaseinfo.xml"/>
<xi:include href="xml/gicallableinfo.xml"/>
<xi:include href="xml/gifunctioninfo.xml"/>
<xi:include href="xml/gicallbackinfo.xml"/>
<xi:include href="xml/gisignalinfo.xml"/>
<xi:include href="xml/givfuncinfo.xml"/>
<xi:include href="xml/giregisteredtypeinfo.xml"/>
<xi:include href="xml/gienuminfo.xml"/>
<xi:include href="xml/gistructinfo.xml"/>
<xi:include href="xml/giunioninfo.xml"/>
<xi:include href="xml/giobjectinfo.xml"/>
<xi:include href="xml/giinterfaceinfo.xml"/>
<xi:include href="xml/giarginfo.xml"/>
<xi:include href="xml/giconstantinfo.xml"/>
<xi:include href="xml/gifieldinfo.xml"/>
<xi:include href="xml/gipropertyinfo.xml"/>
<xi:include href="xml/gitypeinfo.xml"/>
<xi:include href="xml/givalueinfo.xml"/>
</chapter>
<chapter id="gi-typelib">
<title>GITypelib</title>
<xi:include href="xml/gitypelib.xml" />
<xi:include href="xml/gitypelib-internal.xml"/>
</chapter>
<chapter>
<title>TODO</title>
<xi:include href="xml/girffi.xml"/>
<xi:include href="xml/gi-gir-reference.xml"/>
<!--
&gi-gir-creating;
&gi-gir-parsing;
&gi-gir-verifying;
-->
</chapter>
</part>
<index id="api-index-full">
<title id="index-all">Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-1-29-0" role="1.29.0">
<title>Index of new symbols in 1.29.0</title>
<xi:include href="xml/api-index-1.29.0.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-1-29-17" role="1.29.17">
<title>Index of new symbols in 1.29.17</title>
<xi:include href="xml/api-index-1.29.17.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-1-30-1" role="1.30.1">
<title>Index of new symbols in 1.30.1</title>
<xi:include href="xml/api-index-1.30.1.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-1-34" role="1.34">
<title>Index of new symbols in 1.34</title>
<xi:include href="xml/api-index-1.34.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-1-35-8" role="1.35.8">
<title>Index of new symbols in 1.35.8</title>
<xi:include href="xml/api-index-1.35.8.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml" />
</book>
<chapter id="gi-gir-reference">
<title>The GIR XML format</title>
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE refentry 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 version SYSTEM "version.xml">
]>
<refentry id="gi-gir-reference">
<refmeta>
<refentrytitle role="top_of_page" id="gi-gir-reference.top_of_page">The GIR XML format</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>The GIR XML format</refmiscinfo>
</refmeta>
<refnamediv>
<refname>The GIR XML format</refname>
<refpurpose>The GIR XML format</refpurpose>
</refnamediv>
<para>
This chapter describes the GIR XML markup format.
</para>
<refsect2 id="gi-gir-api">
<title><emphasis>api</emphasis> node</title>
The root node of all GIR documents is the api node.
Possible children: <link linkend="gi-gir-namespace">namespace</link>.
<example>
<title>A GIR fragment showing an api node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace/>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-namespace">
<title><emphasis>namespace</emphasis> node</title>
Parent node: <link linkend="gi-gir-api">api</link>.
Possible children: <link linkend="gi-gir-callback">callback</link>,
<link linkend="gi-gir-class">class</link>,
<link linkend="gi-gir-function">function</link>.
<link linkend="gi-gir-interface">interface</link>.
<example>
<title>A GIR fragment showing an namespace node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<class/>
<function/>
</namespace>
</api>]]></programlisting>
</example>
<refsect2 id="gi-gir-api-node">
<title><emphasis>api</emphasis> node</title>
The root node of all GIR documents is the api node.
Possible children: <link linkend="gi-gir-namespace">namespace</link>.
<example>
<title>A GIR fragment showing an api node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace/>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-namespace">
<title><emphasis>namespace</emphasis> node</title>
Parent node: <link linkend="gi-gir-api">api</link>.
Possible children: <link linkend="gi-gir-callback">callback</link>,
<link linkend="gi-gir-class">class</link>,
<link linkend="gi-gir-function">function</link>.
<link linkend="gi-gir-interface">interface</link>.
<example>
<title>A GIR fragment showing an namespace node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<class/>
<function/>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-class">
<title><emphasis>class</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
Possible children: <link linkend="gi-gir-class">constructor</link>,
<link linkend="gi-gir-field">field</link>,
<link linkend="gi-gir-method">method</link>,
<link linkend="gi-gir-property">property</link>.
<example>
<title>A GIR fragment showing an class node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<class name="Widget">
<constructor/>
<field/>
<method/>
<property/>
<class>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-interface">
<title><emphasis>interface</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
Possible children: <link linkend="gi-gir-field">field</link>,
<link linkend="gi-gir-method">method</link>,
<link linkend="gi-gir-property">property</link>.
<example>
<title>A GIR fragment showing an interface node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<interface name="Buildable">
<field/>
<method/>
<property/>
<interface>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-function">
<title><emphasis>function</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
<example>
<title>A GIR fragment showing an function node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<function name="init">
</function>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-class">
<title><emphasis>class</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
Possible children: <link linkend="gi-gir-class">constructor</link>,
<link linkend="gi-gir-field">field</link>,
<link linkend="gi-gir-method">method</link>,
<link linkend="gi-gir-property">property</link>.
<example>
<title>A GIR fragment showing an class node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<class name="Widget">
<constructor/>
<field/>
<method/>
<property/>
<class>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-interface">
<title><emphasis>interface</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
Possible children: <link linkend="gi-gir-field">field</link>,
<link linkend="gi-gir-method">method</link>,
<link linkend="gi-gir-property">property</link>.
<example>
<title>A GIR fragment showing an interface node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<interface name="Buildable">
<field/>
<method/>
<property/>
<interface>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
<refsect2 id="gi-gir-function">
<title><emphasis>function</emphasis> node</title>
Parent node: <link linkend="gi-gir-namespace">namespace</link>.
<example>
<title>A GIR fragment showing an function node</title>
<programlisting><![CDATA[
<api version="1.0">
<namespace="Gtk">
<function name="init">
</function>
</namespace>
</api>]]></programlisting>
</example>
</refsect2>
</chapter>
</refentry>
<chapter id="gi-gir-reference">
<title>The GIR XML format</title>
<para>
This chapter describes the GIR XML markup format.
</para>
<section id="gi-gir-api">
<title>API node</title>
The root node of all GIR documents is the api node.
Attributes:
<itemizedlist>
<listitem><para>version</para></listitem>