[gobject-introspection] docs: fix up reference docs a bit
- From: Colin Walters <walters src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] docs: fix up reference docs a bit
- Date: Thu, 10 Oct 2013 20:56:39 +0000 (UTC)
commit a737daa16e458e87f189c2535f11f4bd2dde8f1a
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date: Thu Oct 10 22:21:18 2013 +0200
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
.gitignore | 6 +
Makefile-girepository.am | 3 +
autogen.sh | 2 +-
configure.ac | 7 +-
docs/reference/Makefile.am | 142 +++++--
docs/reference/gi-docs.sgml | 83 ----
docs/reference/gi-docs.xml | 174 ++++++++
docs/reference/gi-gir-reference.xml | 221 +++++-----
docs/reference/gi-gir.sgml | 23 -
docs/reference/gi-overview.xml | 52 ---
docs/reference/gi-sections.txt | 405 ++++++++++--------
docs/reference/gi-struct-hierarchy.xml | 1 -
docs/reference/gi.types | 2 -
docs/reference/overview-building.xml | 189 ++++++++
docs/reference/overview-programming.xml | 22 +
docs/reference/version.xml.in | 3 +-
girepository/docs.c | 33 ++
girepository/giarginfo.c | 11 +-
girepository/giarginfo.h | 6 +
girepository/gibaseinfo.c | 16 +-
girepository/gibaseinfo.h | 5 +
girepository/gicallableinfo.c | 35 ++-
girepository/gicallableinfo.h | 6 +
girepository/giconstantinfo.c | 4 +-
girepository/giconstantinfo.h | 6 +
girepository/gienuminfo.c | 25 +-
girepository/gienuminfo.h | 12 +
girepository/gifieldinfo.c | 10 +-
girepository/gifieldinfo.h | 7 +
girepository/gifunctioninfo.c | 11 +-
girepository/gifunctioninfo.h | 11 +
girepository/giinterfaceinfo.c | 7 +-
girepository/giinterfaceinfo.h | 6 +
girepository/ginvoke.c | 34 ++-
girepository/giobjectinfo.c | 6 +-
girepository/giobjectinfo.h | 8 +-
girepository/gipropertyinfo.c | 6 +-
girepository/gipropertyinfo.h | 6 +
girepository/giregisteredtypeinfo.c | 4 +-
girepository/giregisteredtypeinfo.h | 6 +
girepository/girepository.c | 105 ++++--
girepository/girepository.h | 31 +-
girepository/girffi.c | 31 +-
girepository/girffi.h | 18 +-
girepository/giroffsets.c | 2 +-
girepository/gisignalinfo.c | 4 +-
girepository/gisignalinfo.h | 6 +
girepository/gistructinfo.c | 12 +-
girepository/gistructinfo.h | 6 +
girepository/gitypeinfo.c | 5 +-
girepository/gitypeinfo.h | 12 +
girepository/gitypelib-internal.h | 732 +++++++++++++++++-------------
girepository/gitypelib.c | 92 ++++-
girepository/gitypelib.h | 13 +
girepository/gitypes.h | 95 ++++-
girepository/giunioninfo.c | 6 +-
girepository/giunioninfo.h | 6 +
girepository/givfuncinfo.c | 4 +-
girepository/givfuncinfo.h | 6 +
59 files changed, 1864 insertions(+), 938 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 4a4d9c6..798f615 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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
diff --git a/Makefile-girepository.am b/Makefile-girepository.am
index 04ec549..c91c41c 100644
--- a/Makefile-girepository.am
+++ b/Makefile-girepository.am
@@ -1,3 +1,6 @@
+EXTRA_DIST += \
+ girepository/docs.c
+
girepodir = $(includedir)/gobject-introspection-1.0/
girepo_HEADERS = \
girepository/giarginfo.h \
diff --git a/autogen.sh b/autogen.sh
index 51f51c4..58fa019 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -16,7 +16,7 @@ EXTRA_DIST =
CLEANFILES =
EOF
else
- gtkdocize || exit $?
+ gtkdocize --flavour no-tmpl || exit $?
fi
AUTORECONF=`which autoreconf`
diff --git a/configure.ac b/configure.ac
index 1f78408..07bdb46 100644
--- a/configure.ac
+++ b/configure.ac
@@ -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
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 937ac80..d3b3f93 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -1,61 +1,121 @@
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
diff --git a/docs/reference/gi-docs.xml b/docs/reference/gi-docs.xml
new file mode 100644
index 0000000..b6bc54f
--- /dev/null
+++ b/docs/reference/gi-docs.xml
@@ -0,0 +1,174 @@
+<?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>
diff --git a/docs/reference/gi-gir-reference.xml b/docs/reference/gi-gir-reference.xml
index 8d19112..fb97984 100644
--- a/docs/reference/gi-gir-reference.xml
+++ b/docs/reference/gi-gir-reference.xml
@@ -1,114 +1,121 @@
-<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>
diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt
index 8b880cf..59f0d50 100644
--- a/docs/reference/gi-sections.txt
+++ b/docs/reference/gi-sections.txt
@@ -1,126 +1,180 @@
<SECTION>
<FILE>girepository</FILE>
-GICallbackInfo
+<TITLE>GIRepository</TITLE>
GIRepository
-GIRepositoryError
GIRepositoryLoadFlags
-GITypelib
g_irepository_get_default
-g_irepository_prepend_search_path
+g_irepository_get_dependencies
+g_irepository_get_loaded_namespaces
+g_irepository_get_n_infos
+g_irepository_get_info
+g_irepository_get_option_group
+g_irepository_enumerate_versions
+<SUBSECTION>
g_irepository_prepend_library_path
+g_irepository_prepend_search_path
g_irepository_get_search_path
+<SUBSECTION>
g_irepository_load_typelib
+g_irepository_get_typelib_path
g_irepository_is_registered
-g_irepository_find_by_name
g_irepository_require
g_irepository_require_private
-g_irepository_get_dependencies
-g_irepository_get_loaded_namespaces
-g_irepository_find_by_gtype
-g_irepository_get_n_infos
-g_irepository_get_info
-g_irepository_get_typelib_path
+g_irepository_get_c_prefix
g_irepository_get_shared_library
g_irepository_get_version
-g_irepository_get_option_group
-g_irepository_get_c_prefix
+<SUBSECTION>
+g_irepository_find_by_gtype
+g_irepository_find_by_error_domain
+g_irepository_find_by_name
+<SUBSECTION>
g_irepository_dump
-g_irepository_enumerate_versions
+<SUBSECTION>
+gi_cclosure_marshal_generic
+<SUBSECTION>
G_IREPOSITORY_ERROR
-g_typelib_new_from_memory
-g_typelib_new_from_const_memory
-g_typelib_new_from_mapped_file
-g_typelib_free
-g_typelib_symbol
-g_typelib_get_namespace
+GIRepositoryError
<SUBSECTION Standard>
GIRepositoryClass
G_TYPE_IREPOSITORY
G_IREPOSITORY
G_IREPOSITORY_CLASS
-G_IREPOSITORY_GET_CLASS
G_IS_IREPOSITORY
G_IS_IREPOSITORY_CLASS
+G_IREPOSITORY_GET_CLASS
<SUBSECTION Private>
-g_info_new
GIRepositoryPrivate
g_irepository_get_type
g_irepository_error_quark
-GIRealInfo
-GIUnresolvedInfo
</SECTION>
<SECTION>
<FILE>gibaseinfo</FILE>
GIInfoType
-g_info_type_to_string
GIAttributeIter
-GIBaseInfo
+g_info_new
g_base_info_ref
g_base_info_unref
+g_base_info_equal
g_base_info_get_type
-g_base_info_get_name
+g_base_info_get_typelib
g_base_info_get_namespace
-g_base_info_is_deprecated
+g_base_info_get_name
g_base_info_get_attribute
g_base_info_iterate_attributes
g_base_info_get_container
-g_base_info_get_typelib
-g_base_info_equal
+g_base_info_is_deprecated
+<SUBSECTION Standard>
+GI_TYPE_BASE_INFO
+g_base_info_gtype_get_type
<SUBSECTION Private>
GIBaseInfoStub
</SECTION>
<SECTION>
+<FILE>giarginfo</FILE>
+GI_IS_ARG_INFO
+GIArgInfo
+GIDirection
+GIScopeType
+GITransfer
+g_arg_info_get_closure
+g_arg_info_get_destroy
+g_arg_info_get_direction
+g_arg_info_get_ownership_transfer
+g_arg_info_get_scope
+g_arg_info_get_type
+g_arg_info_load_type
+g_arg_info_may_be_null
+g_arg_info_is_caller_allocates
+g_arg_info_is_optional
+g_arg_info_is_return_value
+g_arg_info_is_skip
+</SECTION>
+
+<SECTION>
<FILE>gicallableinfo</FILE>
GI_IS_CALLABLE_INFO
GICallableInfo
-g_callable_info_get_return_type
+g_callable_info_can_throw_gerror
+g_callable_info_get_n_args
+g_callable_info_get_arg
g_callable_info_get_caller_owns
-g_callable_info_may_return_null
g_callable_info_get_return_attribute
+g_callable_info_get_return_type
+g_callable_info_invoke
+g_callable_info_is_method
g_callable_info_iterate_return_attributes
-g_callable_info_get_n_args
-g_callable_info_get_arg
g_callable_info_load_arg
g_callable_info_load_return_type
+g_callable_info_may_return_null
+g_callable_info_skip_return
+</SECTION>
+
+<SECTION>
+<FILE>gicommontypes</FILE>
+GIArgument
+GIUnresolvedInfo
+GITypeTag
+GIArrayType
+GI_TYPE_TAG_N_TYPES
+G_TYPE_TAG_IS_BASIC
+</SECTION>
+
+<SECTION>
+<FILE>gicallbackinfo</FILE>
+GICallbackInfo
</SECTION>
<SECTION>
<FILE>giconstantinfo</FILE>
GI_IS_CONSTANT_INFO
GIConstantInfo
+g_constant_info_free_value
g_constant_info_get_type
g_constant_info_get_value
</SECTION>
<SECTION>
-<FILE>givfuncinfo</FILE>
-GI_IS_VFUNC_INFO
-GIVFuncInfo
-GIVFuncInfoFlags
-g_vfunc_info_get_flags
-g_vfunc_info_get_offset
-g_vfunc_info_get_signal
-g_vfunc_info_get_invoker
+<FILE>gienuminfo</FILE>
+GI_IS_ENUM_INFO
+GI_IS_VALUE_INFO
+GIEnumInfo
+g_enum_info_get_n_values
+g_enum_info_get_value
+g_enum_info_get_n_methods
+g_enum_info_get_method
+g_enum_info_get_storage_type
+g_enum_info_get_error_domain
+g_value_info_get_value
</SECTION>
<SECTION>
-<FILE>gisignalinfo</FILE>
-GI_IS_SIGNAL_INFO
-GISignalInfo
-g_signal_info_get_flags
-g_signal_info_get_class_closure
-g_signal_info_true_stops_emit
+<FILE>gifieldinfo</FILE>
+GI_IS_FIELD_INFO
+GIFieldInfo
+GIFieldInfoFlags
+g_field_info_get_field
+g_field_info_set_field
+g_field_info_get_flags
+g_field_info_get_offset
+g_field_info_get_size
+g_field_info_get_type
</SECTION>
<SECTION>
-<FILE>gipropertyinfo</FILE>
-GI_IS_PROPERTY_INFO
-GIPropertyInfo
-g_property_info_get_flags
-g_property_info_get_type
-g_property_info_get_ownership_transfer
+<FILE>gifunctioninfo</FILE>
+GI_IS_FUNCTION_INFO
+GIFunctionInfo
+GIFunctionInfoFlags
+g_function_info_get_flags
+g_function_info_get_property
+g_function_info_get_symbol
+g_function_info_get_vfunc
+g_function_info_invoke
+G_INVOKE_ERROR
+g_invoke_error_quark
+GInvokeError
</SECTION>
<SECTION>
@@ -139,64 +193,70 @@ g_interface_info_get_signal
g_interface_info_find_signal
g_interface_info_get_n_vfuncs
g_interface_info_get_vfunc
+g_interface_info_find_vfunc
g_interface_info_get_n_constants
g_interface_info_get_constant
g_interface_info_get_iface_struct
-g_interface_info_find_vfunc
</SECTION>
<SECTION>
<FILE>giobjectinfo</FILE>
GI_IS_OBJECT_INFO
GIObjectInfo
-GIObjectInfoGetValueFunction
-GIObjectInfoRefFunction
-GIObjectInfoSetValueFunction
-GIObjectInfoUnrefFunction
-g_object_info_get_type_name
-g_object_info_get_type_init
g_object_info_get_abstract
g_object_info_get_fundamental
g_object_info_get_parent
-g_object_info_get_n_interfaces
-g_object_info_get_interface
+g_object_info_get_type_name
+g_object_info_get_type_init
+<SUBSECTION>
+g_object_info_get_n_constants
+g_object_info_get_constant
+<SUBSECTION>
g_object_info_get_n_fields
g_object_info_get_field
-g_object_info_get_n_properties
-g_object_info_get_property
+<SUBSECTION>
+g_object_info_get_n_interfaces
+g_object_info_get_interface
+<SUBSECTION>
g_object_info_get_n_methods
g_object_info_get_method
g_object_info_find_method
+g_object_info_find_method_using_interfaces
+<SUBSECTION>
+g_object_info_get_n_properties
+g_object_info_get_property
+<SUBSECTION>
g_object_info_get_n_signals
g_object_info_get_signal
+g_object_info_find_signal
+<SUBSECTION>
g_object_info_get_n_vfuncs
g_object_info_get_vfunc
-g_object_info_get_n_constants
-g_object_info_get_constant
-g_object_info_get_class_struct
g_object_info_find_vfunc
-g_object_info_get_unref_function
-g_object_info_get_unref_function_pointer
+g_object_info_find_vfunc_using_interfaces
+<SUBSECTION>
+g_object_info_get_class_struct
g_object_info_get_ref_function
g_object_info_get_ref_function_pointer
+g_object_info_get_unref_function
+g_object_info_get_unref_function_pointer
g_object_info_get_set_value_function
g_object_info_get_set_value_function_pointer
g_object_info_get_get_value_function
g_object_info_get_get_value_function_pointer
+GIObjectInfoRefFunction
+GIObjectInfoUnrefFunction
+GIObjectInfoSetValueFunction
+GIObjectInfoGetValueFunction
</SECTION>
<SECTION>
-<FILE>gienuminfo</FILE>
-GI_IS_ENUM_INFO
-GI_IS_VALUE_INFO
-GIEnumInfo
-GIValueInfo
-g_enum_info_get_n_values
-g_enum_info_get_value
-g_enum_info_get_n_methods
-g_enum_info_get_method
-g_enum_info_get_storage_type
-g_value_info_get_value
+<FILE>gipropertyinfo</FILE>
+GI_IS_PROPERTY_INFO
+GIPropertyInfo
+g_property_info_get_flags
+g_property_info_get_ownership_transfer
+g_property_info_get_type
</SECTION>
<SECTION>
@@ -209,78 +269,52 @@ g_registered_type_info_get_g_type
</SECTION>
<SECTION>
+<FILE>girffi</FILE>
+GIFFIClosureCallback
+GIFunctionInvoker
+GIFFIReturnValue
+gi_type_tag_get_ffi_type
+g_type_info_get_ffi_type
+gi_type_info_extract_ffi_return_value
+g_function_info_prep_invoker
+g_function_invoker_new_for_address
+g_function_invoker_destroy
+g_callable_info_prepare_closure
+g_callable_info_free_closure
+</SECTION>
+
+<SECTION>
+<FILE>gisignalinfo</FILE>
+GI_IS_SIGNAL_INFO
+GISignalInfo
+g_signal_info_get_flags
+g_signal_info_get_class_closure
+g_signal_info_true_stops_emit
+</SECTION>
+
+<SECTION>
<FILE>gistructinfo</FILE>
GI_IS_STRUCT_INFO
GIStructInfo
+g_struct_info_get_alignment
+g_struct_info_get_size
+g_struct_info_is_gtype_struct
+g_struct_info_is_foreign
+<SUBSECTION>
g_struct_info_get_n_fields
g_struct_info_get_field
+<SUBSECTION>
g_struct_info_get_n_methods
g_struct_info_get_method
g_struct_info_find_method
-g_struct_info_get_size
-g_struct_info_get_alignment
-g_struct_info_is_gtype_struct
-g_struct_info_is_foreign
-</SECTION>
-
-<SECTION>
-<FILE>giunioninfo</FILE>
-GI_IS_UNION_INFO
-GIUnionInfo
-g_union_info_get_n_fields
-g_union_info_get_field
-g_union_info_get_n_methods
-g_union_info_get_method
-g_union_info_is_discriminated
-g_union_info_get_discriminator_offset
-g_union_info_get_discriminator_type
-g_union_info_get_discriminator
-g_union_info_find_method
-g_union_info_get_size
-g_union_info_get_alignment
-</SECTION>
-
-<SECTION>
-<FILE>gifieldinfo</FILE>
-GI_IS_FIELD_INFO
-GIFieldInfo
-GIFieldInfoFlags
-g_field_info_get_flags
-g_field_info_get_size
-g_field_info_get_offset
-g_field_info_get_type
-g_field_info_get_field
-g_field_info_set_field
-</SECTION>
-
-<SECTION>
-<FILE>giarginfo</FILE>
-GI_IS_ARG_INFO
-GIArgInfo
-GIDirection
-GIScopeType
-GITransfer
-g_arg_info_get_direction
-g_arg_info_is_caller_allocates
-g_arg_info_is_return_value
-g_arg_info_is_optional
-g_arg_info_may_be_null
-g_arg_info_get_ownership_transfer
-g_arg_info_get_scope
-g_arg_info_get_closure
-g_arg_info_get_destroy
-g_arg_info_get_type
-g_arg_info_load_type
</SECTION>
<SECTION>
<FILE>gitypeinfo</FILE>
GI_IS_TYPE_INFO
-GIArrayType
GITypeInfo
-GITypeTag
-G_TYPE_TAG_IS_BASIC
g_type_tag_to_string
+g_info_type_to_string
g_type_info_is_pointer
g_type_info_get_tag
g_type_info_get_param_type
@@ -288,50 +322,40 @@ g_type_info_get_interface
g_type_info_get_array_length
g_type_info_get_array_fixed_size
g_type_info_is_zero_terminated
-g_type_info_get_n_error_domains
-g_type_info_get_error_domain
g_type_info_get_array_type
</SECTION>
<SECTION>
-<FILE>gifunctioninfo</FILE>
-GI_IS_FUNCTION_INFO
-GIFunctionInfo
-GInvokeError
-GIFunctionInfoFlags
-G_INVOKE_ERROR
-g_function_info_get_symbol
-g_function_info_get_flags
-g_function_info_get_property
-g_function_info_get_vfunc
-g_function_info_invoke
-<SUBSECTION Private>
-g_invoke_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>gierrordomaininfo</FILE>
-GI_IS_ERROR_DOMAIN_INFO
-GIErrorDomainInfo
-g_error_domain_info_get_quark
-g_error_domain_info_get_codes
+<FILE>gitypelib</FILE>
+g_typelib_new_from_memory
+g_typelib_new_from_const_memory
+g_typelib_new_from_mapped_file
+g_typelib_free
+g_typelib_symbol
+g_typelib_get_namespace
+GITypelib
</SECTION>
<SECTION>
-<FILE>gtypelib</FILE>
+<FILE>gitypelib-internal</FILE>
G_IR_MAGIC
GTypelibBlobType
Header
+SectionType
+Section
DirEntry
+SimpleTypeBlobFlags
+SimpleTypeBlob
ArgBlob
SignatureBlob
CommonBlob
FunctionBlob
CallbackBlob
InterfaceTypeBlob
+ArrayTypeDimension
+ArrayTypeBlob
ParamTypeBlob
ErrorTypeBlob
-ErrorDomainBlob
ValueBlob
FieldBlob
RegisteredTypeBlob
@@ -345,27 +369,56 @@ ObjectBlob
InterfaceBlob
ConstantBlob
AttributeBlob
-dimensions
g_typelib_get_dir_entry
+g_typelib_get_dir_entry_by_name
+g_typelib_get_dir_entry_by_gtype_name
+g_typelib_get_dir_entry_by_error_domain
+g_typelib_matches_gtype_name_prefix
g_typelib_check_sanity
g_typelib_get_string
-GTypelibError
+GITypelibError
G_TYPELIB_ERROR
+g_typelib_error_quark
g_typelib_validate
+GITypelibHashBuilder
+<SUBSECTION Standard>
BLOB_IS_REGISTERED_TYPE
-<SUBSECTION Private>
-g_typelib_error_quark
</SECTION>
<SECTION>
-<FILE>girffi</FILE>
-GIFFIClosureCallback
-GIFunctionInvoker
-gi_cclosure_marshal_generic
-g_type_info_get_ffi_type
-g_function_info_prep_invoker
-g_function_invoker_destroy
-g_callable_info_prepare_closure
-g_callable_info_free_closure
+<FILE>giunioninfo</FILE>
+GIUnionInfo
+g_union_info_get_n_fields
+g_union_info_get_field
+g_union_info_get_n_methods
+g_union_info_get_method
+g_union_info_is_discriminated
+g_union_info_get_discriminator_offset
+g_union_info_get_discriminator_type
+g_union_info_get_discriminator
+g_union_info_find_method
+g_union_info_get_size
+g_union_info_get_alignment
+<SUBSECTION Standard>
+GI_IS_UNION_INFO
+</SECTION>
+
+<SECTION>
+<FILE>givalueinfo</FILE>
+GIValueInfo
+</SECTION>
+
+<SECTION>
+<FILE>givfuncinfo</FILE>
+GIVFuncInfo
+GIVFuncInfoFlags
+g_vfunc_info_get_flags
+g_vfunc_info_get_offset
+g_vfunc_info_get_signal
+g_vfunc_info_get_invoker
+g_vfunc_info_get_address
+g_vfunc_info_invoke
+<SUBSECTION Standard>
+GI_IS_VFUNC_INFO
</SECTION>
diff --git a/docs/reference/gi-struct-hierarchy.xml b/docs/reference/gi-struct-hierarchy.xml
index eea5128..1407485 100644
--- a/docs/reference/gi-struct-hierarchy.xml
+++ b/docs/reference/gi-struct-hierarchy.xml
@@ -32,7 +32,6 @@
* <link linkend="gi-GIUnionInfo">GIUnionInfo</link>
* <link linkend="gi-GIArgInfo">GIArgInfo</link>
* <link linkend="gi-GIConstantInfo">GIConstantInfo</link>
- * <link linkend="gi-GIErrorDomainInfo">GIErrorDomainInfo</link>
* <link linkend="gi-GIFieldInfo">GIFieldInfo</link>
* <link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
* <link linkend="gi-GITypeInfo">GITypeInfo</link>
diff --git a/docs/reference/overview-building.xml b/docs/reference/overview-building.xml
new file mode 100644
index 0000000..7c843ce
--- /dev/null
+++ b/docs/reference/overview-building.xml
@@ -0,0 +1,189 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
+]>
+<refentry id="gi-building">
+ <refmeta>
+ <refentrytitle>Compiling the GObject Introspection package</refentrytitle>
+ </refmeta>
+
+ <refnamediv>
+ <refname>Compiling the GObject Introspection Package</refname>
+ <refpurpose>How to compile GObject Introspection itself</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="gi-buildtools">
+ <title>Building on UNIX</title>
+ <para>
+ On UNIX, GObject Introspection uses the standard GNU build system,
+ using <application>autoconf</application> for package
+ configuration and resolving portability issues,
+ <application>automake</application> for building makefiles
+ that comply with the GNU Coding Standards, and
+ <application>libtool</application> for building shared
+ libraries on multiple platforms. The normal sequence for
+ compiling and installing the GObject Introspection package is thus:
+
+ <literallayout>
+ <userinput>./configure</userinput>
+ <userinput>make</userinput>
+ <userinput>make install</userinput>
+ </literallayout>
+ </para>
+
+ <para>
+ The standard options provided by <application>GNU
+ autoconf</application> may be passed to the
+ <command>configure</command> script. Please see the
+ <application>autoconf</application> documentation or run
+ <command>./configure --help</command> for information about
+ the standard options.
+ </para>
+ </refsect1>
+
+ <refsect1 id="dependencies">
+ <title>Dependencies</title>
+ <para>
+ Before you can compile GObject Introspection, you need to have
+ various other tools and libraries installed on your
+ system. The tools needed during the build process (as
+ differentiated from the basic build tools mentioned
+ <link linkend="gi-buildtools">before</link> are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://www.freedesktop.org/software/pkgconfig/";>pkg-config</ulink>
+ is a tool for tracking the compilation flags needed for
+ libraries that are used by the GObjecct Introspection. (For each
+ library, a small <literal>.pc</literal> text file is
+ installed in a standard location that contains the compilation
+ flags needed for that library along with version number
+ information.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The GObject-Introspection makefiles will mostly work with different
+ versions of <command>make</command>, however, there tends to be a
+ few incompatibilities, so the GObject-Introspection team recommends
+ installing <ulink url="http://www.gnu.org/software/make";>GNU
+ make</ulink> if you don't already have it on your system
+ and using it. (It may be called <command>gmake</command>
+ rather than <command>make</command>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ GObject-Introspection depends on a number of libraries and tools
+ maintained under the umbrella of the GNOME project:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The GLib library provides core non-graphical functionality
+ such as high level data types, Unicode manipulation, and
+ an object and type system to C programs. It is available
+ from the <ulink url="ftp.gnome.org/pub/gnome/sources/glib">GNOME
+ FTP site</ulink> or
+ <ulink url="http://download.gnome.org/sources/glib/";>here</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TODO: GTK-Doc
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <title>External dependencies</title>
+ <listitem>
+ <para>
+ Python
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ GObject Introspection has an option dependency on the
+ <ulink url="TODO">libffi</ulink> library. When available,
+ ...
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <para>
+ <ulink url="http://www.cairographics.org";>Cairo</ulink>
+ is a graphics library that supports vector graphics and image
+ compositing. When available, GObject Introspection uses
+ Cairo in its unit tests.
+ </para>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1 id="extra-configuration-options">
+ <title>Extra Configuration Options</title>
+
+ <para>
+ In addition to the normal options, the
+ <command>configure</command> script in the GObject Introspection
+ package supports these additional arguments:
+ </para>
+
+ <formalpara>
+ <title><systemitem>--disable-Bsymbolic</systemitem> and
+ <systemitem>--enable-Bsymbolic</systemitem></title>
+
+ <para>
+ By default, the GObject Introspection package uses the
+ -Bsymbolic-functions linker flag to avoid intra-library
+ PLT jumps. A side-effect of this is that it is no longer
+ possible to override internal uses of GObject Introspection
+ functions with <envar>LD_PRELOAD</envar>. Therefore, it may
+ make sense to turn this feature off in some situations.
+ The <option>--disable-Bsymbolic</option> option allows
+ to do that.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--disable-gtk-doc</systemitem> and
+ <systemitem>--enable-gtk-doc</systemitem></title>
+
+ <para>
+ By default the <command>configure</command> script will try
+ to auto-detect whether the
+ <application>gtk-doc</application> package is installed.
+ If it is, then it will use it to extract and build the
+ documentation for the GObject Introspection package. These options
+ can be used to explicitly control whether
+ <application>gtk-doc</application> should be
+ used or not. If it is not used, the distributed,
+ pre-generated HTML files will be installed instead of
+ building them on your machine.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--disable-doctool</systemitem> and
+ <systemitem>--enable-doctool</systemitem></title>
+
+ <para>
+ TODO
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><systemitem>--with-python</systemitem></title>
+
+ <para>
+ Allows specifying the Python interpreter to use, either as an
+ absolute path, or as a program name. GObject Introspection can
+ be built with Python 2 (at least version 2.6) but does not yet
+ support Python 3.
+ </para>
+ </formalpara>
+ </refsect1>
+
+</refentry>
diff --git a/docs/reference/overview-programming.xml b/docs/reference/overview-programming.xml
new file mode 100644
index 0000000..6511d4b
--- /dev/null
+++ b/docs/reference/overview-programming.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
+]>
+<refentry id="gi-programming">
+ <refmeta>
+ <refentrytitle>Writing introspected libraries</refentrytitle>
+ </refmeta>
+
+ <refnamediv>
+ <refname>Writing introspected libraries</refname>
+ <refpurpose>General considerations when writing introspected libraries</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>TODO</title>
+ <para>
+ ...
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
index d1cc3c7..fefbcc3 100644
--- a/docs/reference/version.xml.in
+++ b/docs/reference/version.xml.in
@@ -1,2 +1 @@
- GOBJECT_INTROSPECTION_VERSION@
- GOBJECT_INTROSPECTION_VERSION@
+ GI_VERSION@
diff --git a/girepository/docs.c b/girepository/docs.c
new file mode 100644
index 0000000..a4798c4
--- /dev/null
+++ b/girepository/docs.c
@@ -0,0 +1,33 @@
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
+ * GObject introspection: Dump introspection data
+ *
+ * Copyright (C) 2013 Dieter Verfaillie <dieterv optionexplicit be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+/* This file collects documentation for macros, typedefs and
+ * the like, which have no good home in any of the 'real' source
+ * files.
+ */
+
+/**
+ * SECTION:gicommontypes
+ * @title: common types
+ * @short_description: TODO
+ *
+ * TODO
+ */
diff --git a/girepository/giarginfo.c b/girepository/giarginfo.c
index d61f4be..572839c 100644
--- a/girepository/giarginfo.c
+++ b/girepository/giarginfo.c
@@ -26,12 +26,12 @@
#include "girepository-private.h"
-/* GIArgInfo function */
+/* GIArgInfo functions */
/**
* SECTION:giarginfo
- * @Short_description: Struct representing an argument
- * @Title: GIArgInfo
+ * @title: GIArgInfo
+ * @short_description: Struct representing an argument
*
* GIArgInfo represents an argument. An argument is always
* part of a #GICallableInfo.
@@ -293,8 +293,9 @@ g_arg_info_get_destroy (GIArgInfo *info)
*
* Obtain the type information for @info.
*
- * Returns: (transfer full): the #GIArgInfo, free it with
- * g_base_info_unref() when done.
+ * Returns: (transfer full): the #GITypeInfo holding the type
+ * information for @info, free it with g_base_info_unref()
+ * when done.
*/
GITypeInfo *
g_arg_info_get_type (GIArgInfo *info)
diff --git a/girepository/giarginfo.h b/girepository/giarginfo.h
index 3f4163e..4045ab9 100644
--- a/girepository/giarginfo.h
+++ b/girepository/giarginfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_ARG_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a GIArgInfo.
+ */
#define GI_IS_ARG_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ARG)
diff --git a/girepository/gibaseinfo.c b/girepository/gibaseinfo.c
index 37893e6..4bbe850 100644
--- a/girepository/gibaseinfo.c
+++ b/girepository/gibaseinfo.c
@@ -71,6 +71,17 @@ _g_info_new_full (GIInfoType type,
return (GIBaseInfo*)info;
}
+/**
+ * g_info_new:
+ * @type: TODO
+ * @container: TODO
+ * @typelib: TODO
+ * @offset: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
GIBaseInfo *
g_info_new (GIInfoType type,
GIBaseInfo *container,
@@ -169,8 +180,8 @@ _g_type_info_init (GIBaseInfo *info,
/**
* SECTION:gibaseinfo
- * @Short_description: Base struct for all GITypelib structs
- * @Title: GIBaseInfo
+ * @title: GIBaseInfo
+ * @short_description: Base struct for all GITypelib structs
*
* GIBaseInfo is the common base struct of all other *Info structs
* accessible through the #GIRepository API.
@@ -209,7 +220,6 @@ _g_type_info_init (GIBaseInfo *info,
* +----<link linkend="gi-GITypeInfo">GITypeInfo</link>
* </synopsis>
* </refsect1>
- *
*/
/**
diff --git a/girepository/gibaseinfo.h b/girepository/gibaseinfo.h
index 54c8ee4..a49dd50 100644
--- a/girepository/gibaseinfo.h
+++ b/girepository/gibaseinfo.h
@@ -33,6 +33,11 @@
G_BEGIN_DECLS
+/**
+ * GIBaseInfoStub:
+ *
+ * TODO
+ */
struct _GIBaseInfoStub {
/* <private> */
gint32 dummy1;
diff --git a/girepository/gicallableinfo.c b/girepository/gicallableinfo.c
index 28c5950..e69e3e9 100644
--- a/girepository/gicallableinfo.c
+++ b/girepository/gicallableinfo.c
@@ -33,8 +33,8 @@
/**
* SECTION:gicallableinfo
- * @Short_description: Struct representing a callable
- * @Title: GICallableInfo
+ * @title: GICallableInfo
+ * @short_description: Struct representing a callable
*
* GICallableInfo represents an entity which is callable.
* Currently a function (#GIFunctionInfo), virtual function,
@@ -85,9 +85,10 @@ signature_offset (GICallableInfo *info)
* g_callable_info_can_throw_gerror:
* @info: a #GICallableInfo
*
- * Returns: %TRUE if this #GICallableInfo can throw a #GError
+ * TODO
*
* Since: 1.34
+ * Returns: %TRUE if this #GICallableInfo can throw a #GError
*/
gboolean
g_callable_info_can_throw_gerror (GICallableInfo *info)
@@ -128,6 +129,7 @@ g_callable_info_can_throw_gerror (GICallableInfo *info)
* is one more C argument than is exposed by introspection: the "self"
* or "this" object.
*
+ * Returns: %TRUE if @info is a method, %FALSE otherwise
* Since: 1.34
*/
gboolean
@@ -430,11 +432,17 @@ g_callable_info_iterate_return_attributes (GICallableInfo *info,
return TRUE;
}
-/* Extract the correct bits from an ffi_arg return value into
+/**
+ * gi_type_info_extract_ffi_return_value:
+ * @return_info: TODO
+ * @ffi_value: TODO
+ * @arg: (out caller-allocates): TODO
+ *
+ * Extract the correct bits from an ffi_arg return value into
* GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152
*
- * Also see the ffi_call man page - the storage requirements for return
- * values are "special".
+ * Also see <citerefentry><refentrytitle>ffi_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ * - the storage requirements for return values are "special".
*/
void
gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
@@ -501,6 +509,21 @@ gi_type_info_extract_ffi_return_value (GITypeInfo *return_info,
}
}
+/**
+ * g_callable_info_invoke:
+ * @info: TODO
+ * @function: TODO
+ * @in_args: TODO
+ * @n_in_args: TODO
+ * @out_args: TODO
+ * @n_out_args: TODO
+ * @return_value: TODO
+ * @is_method: TODO
+ * @throws: TODO
+ * @error: TODO
+ *
+ * TODO
+ */
gboolean
g_callable_info_invoke (GIFunctionInfo *info,
gpointer function,
diff --git a/girepository/gicallableinfo.h b/girepository/gicallableinfo.h
index a7d7079..71f9d0c 100644
--- a/girepository/gicallableinfo.h
+++ b/girepository/gicallableinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_CALLABLE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GICallableInfo or derived from it.
+ */
#define GI_IS_CALLABLE_INFO(info) \
((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FUNCTION) || \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_CALLBACK) || \
diff --git a/girepository/giconstantinfo.c b/girepository/giconstantinfo.c
index 88220b4..7b2f716 100644
--- a/girepository/giconstantinfo.c
+++ b/girepository/giconstantinfo.c
@@ -29,8 +29,8 @@
/**
* SECTION:giconstantinfo
- * @Short_description: Struct representing a constant
- * @Title: GIConstantInfo
+ * @title: GIConstantInfo
+ * @short_description: Struct representing a constant
*
* GIConstantInfo represents a constant. A constant has a type associated
* which can be obtained by calling g_constant_info_get_type() and a value,
diff --git a/girepository/giconstantinfo.h b/girepository/giconstantinfo.h
index 2bbf956..2ce1dca 100644
--- a/girepository/giconstantinfo.h
+++ b/girepository/giconstantinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_CONSTANT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIConstantInfo.
+ */
#define GI_IS_CONSTANT_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_CONSTANT)
diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c
index 400a56d..253ec68 100644
--- a/girepository/gienuminfo.c
+++ b/girepository/gienuminfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:gienuminfo
- * @Short_description: Structs representing an enumeration and its values
- * @Title: GIEnumInfo
+ * @title: GIEnumInfo
+ * @short_description: Structs representing an enumeration and its values
*
* A GIEnumInfo represents an enumeration and a GIValueInfo struct represents a value
* of an enumeration. The GIEnumInfo contains a set of values and a type
@@ -46,13 +46,13 @@
*/
/**
-* g_enum_info_get_n_values:
-* @info: a #GIEnumInfo
-*
-* Obtain the number of values this enumeration contains.
-*
-* Returns: the number of enumeration values
-*/
+ * g_enum_info_get_n_values:
+ * @info: a #GIEnumInfo
+ *
+ * Obtain the number of values this enumeration contains.
+ *
+ * Returns: the number of enumeration values
+ */
gint
g_enum_info_get_n_values (GIEnumInfo *info)
{
@@ -76,7 +76,6 @@ g_enum_info_get_n_values (GIEnumInfo *info)
*
* Returns: (transfer none): the string form of the error domain associated
* with this enum, or %NULL.
- *
* Since: 1.29.17
*/
const gchar *
@@ -131,7 +130,6 @@ g_enum_info_get_value (GIEnumInfo *info,
* Obtain the number of methods that this enum type has.
*
* Returns: number of methods
- *
* Since: 1.29.17
*/
gint
@@ -157,7 +155,6 @@ g_enum_info_get_n_methods (GIEnumInfo *info)
*
* Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
* g_base_info_unref() when done.
- *
* Since: 1.29.17
*/
GIFunctionInfo *
@@ -189,12 +186,12 @@ g_enum_info_get_method (GIEnumInfo *info,
*
* Obtain the tag of the type used for the enum in the C ABI. This will
* will be a signed or unsigned integral type.
-
+ *
* Note that in the current implementation the width of the type is
* computed correctly, but the signed or unsigned nature of the type
* may not match the sign of the type used by the C compiler.
*
- * Return Value: the storage type for the enumeration
+ * Returns: the storage type for the enumeration
*/
GITypeTag
g_enum_info_get_storage_type (GIEnumInfo *info)
diff --git a/girepository/gienuminfo.h b/girepository/gienuminfo.h
index 0b9a9e1..257e4c1 100644
--- a/girepository/gienuminfo.h
+++ b/girepository/gienuminfo.h
@@ -31,10 +31,22 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_ENUM_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIEnumInfo.
+ */
#define GI_IS_ENUM_INFO(info) \
((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ENUM) || \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FLAGS))
+/**
+ * GI_IS_VALUE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIValueInfo.
+ */
#define GI_IS_VALUE_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_VALUE)
diff --git a/girepository/gifieldinfo.c b/girepository/gifieldinfo.c
index 1d9a20d..2bbc021 100644
--- a/girepository/gifieldinfo.c
+++ b/girepository/gifieldinfo.c
@@ -29,13 +29,13 @@
/**
* SECTION:gifieldinfo
- * @Short_description: Struct representing a struct or union field
- * @Title: GIFieldInfo
+ * @title: GIFieldInfo
+ * @short_description: Struct representing a struct or union field
*
* A GIFieldInfo struct represents a field of a struct (see #GIStructInfo),
* union (see #GIUnionInfo) or an object (see #GIObjectInfo). The GIFieldInfo
* is fetched by calling g_struct_info_get_field(), g_union_info_get_field()
- * or g_object_info_get_value().
+ * or g_object_info_get_field().
* A field has a size, type and a struct offset asssociated and a set of flags,
* which is currently #GI_FIELD_IS_READABLE or #GI_FIELD_IS_WRITABLE.
*
@@ -167,7 +167,7 @@ g_field_info_get_type (GIFieldInfo *info)
* @mem: pointer to a block of memory representing a C structure or union
* @value: a #GIArgument into which to store the value retrieved
*
- * Reads a field identified by a #GFieldInfo from a C structure or
+ * Reads a field identified by a #GIFieldInfo from a C structure or
* union. This only handles fields of simple C types. It will fail
* for a field of a composite type like a nested structure or union
* even if that is actually readable.
@@ -355,7 +355,7 @@ g_field_info_get_field (GIFieldInfo *field_info,
* @mem: pointer to a block of memory representing a C structure or union
* @value: a #GIArgument holding the value to store
*
- * Writes a field identified by a #GFieldInfo to a C structure or
+ * Writes a field identified by a #GIFieldInfo to a C structure or
* union. This only handles fields of simple C types. It will fail
* for a field of a composite type like a nested structure or union
* even if that is actually writable. Note also that that it will refuse
diff --git a/girepository/gifieldinfo.h b/girepository/gifieldinfo.h
index 4ca5409..56a2e22 100644
--- a/girepository/gifieldinfo.h
+++ b/girepository/gifieldinfo.h
@@ -31,6 +31,13 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_FIELD_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIFieldInfo.
+ *
+ */
#define GI_IS_FIELD_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FIELD)
diff --git a/girepository/gifunctioninfo.c b/girepository/gifunctioninfo.c
index a5858c7..ecd6127 100644
--- a/girepository/gifunctioninfo.c
+++ b/girepository/gifunctioninfo.c
@@ -30,8 +30,8 @@
/**
* SECTION:gifunctioninfo
- * @Short_description: Struct representing a function
- * @Title: GIFunctionInfo
+ * @title: GIFunctionInfo
+ * @short_description: Struct representing a function
*
* GIFunctionInfo represents a function, method or constructor.
* To find out what kind of entity a #GIFunctionInfo represents, call
@@ -205,6 +205,13 @@ g_function_info_get_vfunc (GIFunctionInfo *info)
return g_interface_info_get_vfunc (container, blob->index);
}
+/**
+ * g_invoke_error_quark:
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
GQuark
g_invoke_error_quark (void)
{
diff --git a/girepository/gifunctioninfo.h b/girepository/gifunctioninfo.h
index 7a9ecae..7987c92 100644
--- a/girepository/gifunctioninfo.h
+++ b/girepository/gifunctioninfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_FUNCTION_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIFunctionInfo.
+ */
#define GI_IS_FUNCTION_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FUNCTION)
@@ -39,6 +45,11 @@ GIFunctionInfoFlags g_function_info_get_flags (GIFunctionInfo *info);
GIPropertyInfo * g_function_info_get_property (GIFunctionInfo *info);
GIVFuncInfo * g_function_info_get_vfunc (GIFunctionInfo *info);
+/**
+ * G_INVOKE_ERROR:
+ *
+ * TODO
+ */
#define G_INVOKE_ERROR (g_invoke_error_quark ())
GQuark g_invoke_error_quark (void);
diff --git a/girepository/giinterfaceinfo.c b/girepository/giinterfaceinfo.c
index f998da4..481fc54 100644
--- a/girepository/giinterfaceinfo.c
+++ b/girepository/giinterfaceinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:giinterfaceinfo
- * @Short_description: Struct representing a GInterface
- * @Title: GIInterfaceInfo
+ * @title: GIInterfaceInfo
+ * @short_description: Struct representing a GInterface
*
* GIInterfaceInfo represents a #GInterface type.
*
@@ -297,9 +297,10 @@ g_interface_info_get_signal (GIInterfaceInfo *info,
* @info: a #GIInterfaceInfo
* @name: Name of signal
*
+ * TODO
+ *
* Returns: (transfer full): Info for the signal with name @name in @info, or
* %NULL on failure.
- *
* Since: 1.34
*/
GISignalInfo *
diff --git a/girepository/giinterfaceinfo.h b/girepository/giinterfaceinfo.h
index ce40cda..ec33a63 100644
--- a/girepository/giinterfaceinfo.h
+++ b/girepository/giinterfaceinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_INTERFACE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIInterfaceInfo.
+ */
#define GI_IS_INTERFACE_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_INTERFACE)
diff --git a/girepository/ginvoke.c b/girepository/ginvoke.c
index 5c0ace4..6eba9fc 100644
--- a/girepository/ginvoke.c
+++ b/girepository/ginvoke.c
@@ -28,6 +28,13 @@
#include "girffi.h"
#include "config.h"
+/**
+ * value_to_ffi_type:
+ * @gvalue: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
static ffi_type *
value_to_ffi_type (const GValue *gvalue, gpointer *value)
{
@@ -89,7 +96,14 @@ value_to_ffi_type (const GValue *gvalue, gpointer *value)
return rettype;
}
-/* See comment aboe set_gargument_from_ffi_return_value() */
+/**
+ * g_value_to_ffi_return_type:
+ * @gvalue: TODO
+ * @ffi_value: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
static ffi_type *
g_value_to_ffi_return_type (const GValue *gvalue,
const GIArgument *ffi_value,
@@ -153,6 +167,13 @@ g_value_to_ffi_return_type (const GValue *gvalue,
return rettype;
}
+/**
+ * g_value_from_ffi_value:
+ * @gvalue: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
static void
g_value_from_ffi_value (GValue *gvalue,
const GIArgument *value)
@@ -210,6 +231,17 @@ g_value_from_ffi_value (GValue *gvalue,
}
+/**
+ * gi_cclosure_marshal_generic:
+ * @closure: TODO
+ * @return_gvalue: TODO
+ * @n_param_values: TODO
+ * @param_values: TODO
+ * @invocation_hint: TODO
+ * @marshal_data: TODO
+ *
+ * TODO
+ */
void
gi_cclosure_marshal_generic (GClosure *closure,
GValue *return_gvalue,
diff --git a/girepository/giobjectinfo.c b/girepository/giobjectinfo.c
index 7ba2a93..b0aff37 100644
--- a/girepository/giobjectinfo.c
+++ b/girepository/giobjectinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:giobjectinfo
- * @Short_description: Struct representing a GObject
- * @Title: GIObjectInfo
+ * @title: GIObjectInfo
+ * @short_description: Struct representing a GObject
*
* GIObjectInfo represents a #GObject. This doesn't represent a specific
* instance of a GObject, instead this represent the object type (eg class).
@@ -534,6 +534,8 @@ g_object_info_get_signal (GIObjectInfo *info,
* @info: a #GIObjectInfo
* @name: Name of signal
*
+ * TODO
+ *
* Returns: Info for the signal with name @name in @info, or %NULL on failure.
*/
GISignalInfo *
diff --git a/girepository/giobjectinfo.h b/girepository/giobjectinfo.h
index ee4b8a8..0620677 100644
--- a/girepository/giobjectinfo.h
+++ b/girepository/giobjectinfo.h
@@ -46,7 +46,6 @@ typedef void * (*GIObjectInfoRefFunction) (void *object);
* @object: object instance pointer
*
* Decreases the reference count of an object instance.
- *
*/
typedef void (*GIObjectInfoUnrefFunction) (void *object);
@@ -56,7 +55,6 @@ typedef void (*GIObjectInfoUnrefFunction) (void *object);
* @object: object instance pointer
*
* Update @value and attach the object instance pointer @object to it.
- *
*/
typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
@@ -70,6 +68,12 @@ typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
*/
typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value);
+/**
+ * GI_IS_OBJECT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIObjectInfo.
+ */
#define GI_IS_OBJECT_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_OBJECT)
diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c
index 61316cb..77a11cb 100644
--- a/girepository/gipropertyinfo.c
+++ b/girepository/gipropertyinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:gipropertyinfo
- * @Short_description: Struct representing a property
- * @Title: GIPropertyInfo
+ * @title: GIPropertyInfo
+ * @short_description: Struct representing a property
*
* GIPropertyInfo represents a property. A property belongs to
* either a #GIObjectInfo or a #GIInterfaceInfo.
@@ -47,7 +47,7 @@
* g_property_info_get_flags:
* @info: a #GIPropertyInfo
*
- * Obtain the flags for this property info. See #GParamFags for
+ * Obtain the flags for this property info. See #GParamFlags for
* more information about possible flag values.
*
* Returns: the flags
diff --git a/girepository/gipropertyinfo.h b/girepository/gipropertyinfo.h
index 14b18b4..7644664 100644
--- a/girepository/gipropertyinfo.h
+++ b/girepository/gipropertyinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_PROPERTY_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIPropertyInfo.
+ */
#define GI_IS_PROPERTY_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_PROPERTY)
diff --git a/girepository/giregisteredtypeinfo.c b/girepository/giregisteredtypeinfo.c
index 6e3d31e..e45e060 100644
--- a/girepository/giregisteredtypeinfo.c
+++ b/girepository/giregisteredtypeinfo.c
@@ -30,8 +30,8 @@
/**
* SECTION:giregisteredtypeinfo
- * @Short_description: Struct representing a struct with a GType
- * @Title: GIRegisteredTypeInfo
+ * @title: GIRegisteredTypeInfo
+ * @short_description: Struct representing a struct with a GType
*
* GIRegisteredTypeInfo represents an entity with a GType associated. Could
* be either a #GIEnumInfo, #GIInterfaceInfo, #GIObjectInfo, #GIStructInfo or a
diff --git a/girepository/giregisteredtypeinfo.h b/girepository/giregisteredtypeinfo.h
index d46d738..e5db25b 100644
--- a/girepository/giregisteredtypeinfo.h
+++ b/girepository/giregisteredtypeinfo.h
@@ -32,6 +32,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_REGISTERED_TYPE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIRegisteredTypeInfo or derived from it.
+ */
#define GI_IS_REGISTERED_TYPE_INFO(info) \
((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_BOXED) || \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ENUM) || \
diff --git a/girepository/girepository.c b/girepository/girepository.c
index 93c2372..6fc7c77 100644
--- a/girepository/girepository.c
+++ b/girepository/girepository.c
@@ -34,6 +34,17 @@
#include "config.h"
+
+/**
+ * SECTION:girepository
+ * @short_description: GObject Introspection repository manager
+ * @include: girepository.h
+ *
+ * #GIRepository is used to manage repositories of namespaces. Namespaces
+ * are represented on disk by type libraries (.typelib files).
+ */
+
+
static GIRepository *default_repository = NULL;
static GSList *search_path = NULL;
static GSList *override_search_path = NULL;
@@ -146,8 +157,9 @@ init_globals (void)
char *typelib_dir;
const gchar *type_lib_path_env;
- /* This variable is intended to take precedence over both the default
- * search path, as well as anything written into code with g_irepository_prepend_search_path.
+ /* This variable is intended to take precedence over both:
+ * - the default search path;
+ * - all g_irepository_prepend_search_path() calls.
*/
type_lib_path_env = g_getenv ("GI_TYPELIB_PATH");
@@ -186,6 +198,14 @@ init_globals (void)
g_once_init_leave (&initialized, 1);
}
+/**
+ * g_irepository_prepend_search_path:
+ * @directory: (type filename): directory name to prepend to the typelib
+ * search path
+ *
+ * Prepends @directory to the typelib search path.
+ * See g_irepository_get_search_path().
+ */
void
g_irepository_prepend_search_path (const char *directory)
{
@@ -196,11 +216,11 @@ g_irepository_prepend_search_path (const char *directory)
/**
* g_irepository_get_search_path:
*
- * Returns the search path the GIRepository will use when looking for typelibs.
- * The string is internal to GIRespository and should not be freed, nor should
- * the elements.
+ * Returns the current search path #GIRepository will use when loading
+ * typelib files. The list is internal to #GIRespository and should not
+ * be freed, nor should its string elements.
*
- * Return value: (element-type filename) (transfer none): list of strings
+ * Returns: (element-type filename) (transfer none): #GSList of strings
*/
GSList *
g_irepository_get_search_path (void)
@@ -412,17 +432,19 @@ register_internal (GIRepository *repository,
/**
* g_irepository_get_dependencies:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace of interest
*
- * Return an array of all (transitive) dependencies for namespace
- * @namespace_, including version. The returned strings are of the
- * form <code>namespace-version</code>.
+ * Return an array of all (transitive) versioned dependencies for
+ * @namespace_. Returned strings are of the form
+ * <code>namespace-version</code>.
*
- * Note: The namespace must have already been loaded using a function
+ * Note: @namespace_ must have already been loaded using a function
* such as g_irepository_require() before calling this function.
*
- * Returns: (transfer full): Zero-terminated string array of versioned dependencies
+ * Returns: (transfer full): Zero-terminated string array of versioned
+ * dependencies
*/
char **
g_irepository_get_dependencies (GIRepository *repository,
@@ -440,6 +462,16 @@ g_irepository_get_dependencies (GIRepository *repository,
return get_typelib_dependencies (typelib);
}
+/**
+ * g_irepository_load_typelib:
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
+ * @typelib: TODO
+ * @flags: TODO
+ * @error: TODO
+ *
+ * TODO
+ */
const char *
g_irepository_load_typelib (GIRepository *repository,
GITypelib *typelib,
@@ -478,7 +510,8 @@ g_irepository_load_typelib (GIRepository *repository,
/**
* g_irepository_is_registered:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace of interest
* @version: (allow-none): Required version, may be %NULL for latest
*
@@ -503,13 +536,13 @@ g_irepository_is_registered (GIRepository *repository,
/**
* g_irepository_get_default:
*
- * Returns the singleton process-global default #GIRepository. It is
+ * Returns the singleton process-global default #GIRepository. It is
* not currently supported to have multiple repositories in a
* particular process, but this function is provided in the unlikely
* eventuality that it would become possible, and as a convenience for
* higher level language bindings to conform to the GObject method
* call conventions.
-
+ *
* All methods on #GIRepository also accept %NULL as an instance
* parameter to mean this default repository, which is usually more
* convenient for C.
@@ -524,7 +557,8 @@ g_irepository_get_default (void)
/**
* g_irepository_get_n_infos:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the number of metadata entries in
@@ -555,7 +589,8 @@ g_irepository_get_n_infos (GIRepository *repository,
/**
* g_irepository_get_info:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace to inspect
* @index: 0-based offset into namespace metadata for entry
*
@@ -629,7 +664,8 @@ find_by_gtype (GHashTable *table, FindByGTypeData *data, gboolean check_prefix)
/**
* g_irepository_find_by_gtype:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @gtype: GType to search for
*
* Searches all loaded namespaces for a particular #GType. Note that
@@ -717,7 +753,8 @@ g_irepository_find_by_gtype (GIRepository *repository,
/**
* g_irepository_find_by_name:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace which will be searched
* @name: Entry name to find
*
@@ -776,7 +813,8 @@ find_by_error_domain_foreach (gpointer key,
/**
* g_irepository_find_by_error_domain:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @domain: a #GError domain
*
* Searches for the enum type corresponding to the given #GError
@@ -786,7 +824,6 @@ find_by_error_domain_foreach (gpointer key,
*
* Returns: (transfer full): #GIEnumInfo representing metadata about @domain's
* enum type, or %NULL
- *
* Since: 1.29.17
*/
GIEnumInfo *
@@ -839,7 +876,8 @@ collect_namespaces (gpointer key,
/**
* g_irepository_get_loaded_namespaces:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
*
* Return the list of currently loaded namespaces.
*
@@ -868,7 +906,8 @@ g_irepository_get_loaded_namespaces (GIRepository *repository)
/**
* g_irepository_get_version:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the loaded version associated with the given
@@ -900,7 +939,8 @@ g_irepository_get_version (GIRepository *repository,
/**
* g_irepository_get_shared_library:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the full path to the shared C library
@@ -937,7 +977,8 @@ g_irepository_get_shared_library (GIRepository *repository,
/**
* g_irepository_get_c_prefix:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: Namespace to inspect
*
* This function returns the "C prefix", or the C level namespace
@@ -973,13 +1014,14 @@ g_irepository_get_c_prefix (GIRepository *repository,
/**
* g_irepository_get_typelib_path:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: GI namespace to use, e.g. "Gtk"
*
* If namespace @namespace_ is loaded, return the full path to the
* .typelib file it was loaded from. If the typelib for
* namespace @namespace_ was included in a shared library, return
- * the special string "$lt;builtin$gt;".
+ * the special string "<builtin>".
*
* Returns: Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded
*/
@@ -1248,7 +1290,8 @@ find_namespace_latest (const gchar *namespace,
/**
* g_irepository_enumerate_versions:
- * @repository: (allow-none): the repository
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: GI namespace, e.g. "Gtk"
*
* Obtain an unordered list of versions (either currently loaded or
@@ -1408,7 +1451,8 @@ require_internal (GIRepository *repository,
/**
* g_irepository_require:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @namespace_: GI namespace to use, e.g. "Gtk"
* @version: (allow-none): Version of namespace, may be %NULL for latest
* @flags: Set of %GIRepositoryLoadFlags, may be 0
@@ -1442,7 +1486,8 @@ g_irepository_require (GIRepository *repository,
/**
* g_irepository_require_private:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ * process-global default #GIRepository
* @typelib_dir: Private directory where to find the requested typelib
* @namespace_: GI namespace to use, e.g. "Gtk"
* @version: (allow-none): Version of namespace, may be %NULL for latest
diff --git a/girepository/girepository.h b/girepository/girepository.h
index 2b2b171..dea250d 100644
--- a/girepository/girepository.h
+++ b/girepository/girepository.h
@@ -56,29 +56,34 @@ G_BEGIN_DECLS
#define G_IS_IREPOSITORY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_IREPOSITORY))
#define G_IREPOSITORY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_IREPOSITORY,
GIRepositoryClass))
+/**
+ * GIRepository:
+ *
+ * The GIRepository structure contains private data and should only be
+ * accessed using the provided API.
+ */
typedef struct _GIRepository GIRepository;
typedef struct _GIRepositoryClass GIRepositoryClass;
typedef struct _GIRepositoryPrivate GIRepositoryPrivate;
struct _GIRepository
{
- GObject parent;
-
/*< private >*/
+ GObject parent;
GIRepositoryPrivate *priv;
};
struct _GIRepositoryClass
{
+ /*< private >*/
GObjectClass parent;
};
/**
* GIRepositoryLoadFlags:
- * @G_IREPOSITORY_LOAD_FLAG_LAZY: Load the types lazily.
+ * @G_IREPOSITORY_LOAD_FLAG_LAZY: Lazily load the typelib.
*
- * Flags that controlls how a typelib is loaded by
- * GIRepositry, used by g_irepository_load_typelib().
+ * Flags that control how a typelib is loaded.
*/
typedef enum
{
@@ -144,11 +149,14 @@ gboolean g_irepository_dump (const char *arg, GError **error);
* GIRepositoryError:
* @G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND: the typelib could not be found.
* @G_IREPOSITORY_ERROR_NAMESPACE_MISMATCH: the namespace does not match the
- * requested namespace.
+ * requested namespace.
* @G_IREPOSITORY_ERROR_NAMESPACE_VERSION_CONFLICT: the version of the
- * typelib does not match the requested version.
+ * typelib does not match the requested version.
* @G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND: the library used by the typelib
- * could not be found.
+ * could not be found.
+ *
+ * An error code used with #G_IREPOSITORY_ERROR in a #GError returned
+ * from a #GIRepository routine.
*/
typedef enum
{
@@ -158,6 +166,13 @@ typedef enum
G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND
} GIRepositoryError;
+/**
+ * G_IREPOSITORY_ERROR:
+ *
+ * Error domain for #GIRepository. Errors in this domain will be from the
+ * #GIRepositoryError enumeration. See #GError for more information on
+ * error domains.
+ */
#define G_IREPOSITORY_ERROR (g_irepository_error_quark ())
GQuark g_irepository_error_quark (void);
diff --git a/girepository/girffi.c b/girepository/girffi.c
index f4c80ea..30642fe 100644
--- a/girepository/girffi.c
+++ b/girepository/girffi.c
@@ -33,6 +33,14 @@
#include "girepository.h"
#include "girepository-private.h"
+/**
+ * SECTION:girffi
+ * @short_description: TODO
+ * @title: girffi
+ *
+ * TODO
+ */
+
static ffi_type *
gi_type_tag_get_ffi_type_internal (GITypeTag tag,
gboolean is_pointer,
@@ -103,22 +111,26 @@ gi_type_tag_get_ffi_type_internal (GITypeTag tag,
/**
* gi_type_tag_get_ffi_type:
- * @tag: A #GITypeTag
+ * @type_tag: A #GITypeTag
* @is_pointer: Whether or not this is a pointer type
*
+ * TODO
+ *
* Returns: A #ffi_type corresponding to the platform default C ABI for @tag and @is_pointer.
*/
ffi_type *
-gi_type_tag_get_ffi_type (GITypeTag tag,
+gi_type_tag_get_ffi_type (GITypeTag type_tag,
gboolean is_pointer)
{
- return gi_type_tag_get_ffi_type_internal (tag, is_pointer, FALSE);
+ return gi_type_tag_get_ffi_type_internal (type_tag, is_pointer, FALSE);
}
/**
* g_type_info_get_ffi_type:
* @info: A #GITypeInfo
*
+ * TODO
+ *
* Returns: A #ffi_type corresponding to the platform default C ABI for @info.
*/
ffi_type *
@@ -150,7 +162,9 @@ g_type_info_get_ffi_type (GITypeInfo *info)
* @callable_info: a callable info from a typelib
* @n_args_p: (out): The number of arguments
*
- * Return value: an array of ffi_type*. The array itself
+ * TODO
+ *
+ * Returns: an array of ffi_type*. The array itself
* should be freed using g_free() after use.
*/
static ffi_type **
@@ -217,7 +231,8 @@ g_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
*
* Fetches the ffi_type for a corresponding return value of
* a #GICallableInfo
- * Return value: the ffi_type for the return value
+ *
+ * Returns: the ffi_type for the return value
*/
static ffi_type *
g_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
@@ -316,7 +331,7 @@ g_function_invoker_new_for_address (gpointer addr,
}
/**
- * g_function_info_invoker_destroy:
+ * g_function_invoker_destroy:
* @invoker: A #GIFunctionInvoker
*
* Release all resources allocated for the internals of @invoker; callers
@@ -343,8 +358,8 @@ typedef struct {
*
* Prepares a callback for ffi invocation.
*
- * Return value: the ffi_closure or NULL on error.
- * The return value should be freed by calling g_callable_info_free_closure().
+ * Returns: the ffi_closure or NULL on error. The return value
+ * should be freed by calling g_callable_info_free_closure().
*/
ffi_closure *
g_callable_info_prepare_closure (GICallableInfo *callable_info,
diff --git a/girepository/girffi.h b/girepository/girffi.h
index 56caff7..50cabb1 100644
--- a/girepository/girffi.h
+++ b/girepository/girffi.h
@@ -27,6 +27,15 @@
G_BEGIN_DECLS
+/**
+ * GIFFIClosureCallback:
+ * @Param1: TODO
+ * @Param2: TODO
+ * @Param3: TODO
+ * @Param4: TODO
+ *
+ * TODO
+ */
typedef void (*GIFFIClosureCallback) (ffi_cif *,
void *,
void **,
@@ -35,7 +44,9 @@ typedef void (*GIFFIClosureCallback) (ffi_cif *,
/**
* GIFunctionInvoker:
* @cif: the cif
- * @native_address: the native adress
+ * @native_address: the native address
+ *
+ * TODO
*/
typedef struct _GIFunctionInvoker GIFunctionInvoker;
@@ -46,6 +57,11 @@ struct _GIFunctionInvoker {
gpointer padding[3];
};
+/**
+ * GIFFIReturnValue:
+ *
+ * TODO
+ */
typedef GIArgument GIFFIReturnValue;
ffi_type * gi_type_tag_get_ffi_type (GITypeTag type_tag, gboolean is_pointer);
diff --git a/girepository/giroffsets.c b/girepository/giroffsets.c
index 368332e..84278b8 100644
--- a/girepository/giroffsets.c
+++ b/girepository/giroffsets.c
@@ -497,7 +497,7 @@ check_needs_computation (GIrTypelibBuild *build,
return alignment == 0;
}
-/**
+/*
* _g_ir_node_compute_offsets:
* @build: Current typelib build
* @node: a #GIrNode
diff --git a/girepository/gisignalinfo.c b/girepository/gisignalinfo.c
index f4110c3..be75276 100644
--- a/girepository/gisignalinfo.c
+++ b/girepository/gisignalinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:gisignalinfo
- * @Short_description: Struct representing a signal
- * @Title: GISignalInfo
+ * @title: GISignalInfo
+ * @short_description: Struct representing a signal
*
* GISignalInfo represents a signal. It's a sub-struct of #GICallableInfo
* and contains a set of flags and a class closure.
diff --git a/girepository/gisignalinfo.h b/girepository/gisignalinfo.h
index e3a1e4a..8502610 100644
--- a/girepository/gisignalinfo.h
+++ b/girepository/gisignalinfo.h
@@ -32,6 +32,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_SIGNAL_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GISignalInfo.
+ */
#define GI_IS_SIGNAL_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_SIGNAL)
diff --git a/girepository/gistructinfo.c b/girepository/gistructinfo.c
index dc17e32..f205e7c 100644
--- a/girepository/gistructinfo.c
+++ b/girepository/gistructinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:gistructinfo
- * @Short_description: Struct representing a C structure
- * @Title: GIStructInfo
+ * @title: GIStructInfo
+ * @short_description: Struct representing a C structure
*
* GIStructInfo represents a generic C structure type.
*
@@ -212,6 +212,14 @@ g_struct_info_get_alignment (GIStructInfo *info)
return blob->alignment;
}
+/**
+ * g_struct_info_is_foreign:
+ * @info: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
gboolean
g_struct_info_is_foreign (GIStructInfo *info)
{
diff --git a/girepository/gistructinfo.h b/girepository/gistructinfo.h
index 1d10708..4300534 100644
--- a/girepository/gistructinfo.h
+++ b/girepository/gistructinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_STRUCT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIStructInfo.
+ */
#define GI_IS_STRUCT_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_STRUCT)
diff --git a/girepository/gitypeinfo.c b/girepository/gitypeinfo.c
index a43fbc1..3c17f56 100644
--- a/girepository/gitypeinfo.c
+++ b/girepository/gitypeinfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:gitypeinfo
- * @Short_description: Struct representing a type
- * @Title: GITypeInfo
+ * @title: GITypeInfo
+ * @short_description: Struct representing a type
*
* GITypeInfo represents a type. You can retrieve a type info from
* an argument (see #GIArgInfo), a functions return value (see #GIFunctionInfo),
@@ -48,7 +48,6 @@
* +----GITypeInfo
* </synopsis>
* </refsect1>
- *
*/
/**
diff --git a/girepository/gitypeinfo.h b/girepository/gitypeinfo.h
index ef834b1..7591799 100644
--- a/girepository/gitypeinfo.h
+++ b/girepository/gitypeinfo.h
@@ -31,9 +31,21 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_TYPE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GITypeInfo.
+ */
#define GI_IS_TYPE_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_TYPE)
+/**
+ * G_TYPE_TAG_IS_BASIC
+ * @tag: a type tag
+ *
+ * Checks if @tag is a basic type.
+ */
#define G_TYPE_TAG_IS_BASIC(tag) (tag < GI_TYPE_TAG_ARRAY || tag == GI_TYPE_TAG_UNICHAR)
const gchar* g_type_tag_to_string (GITypeTag type);
diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h
index ac71008..23f4d62 100644
--- a/girepository/gitypelib-internal.h
+++ b/girepository/gitypelib-internal.h
@@ -30,7 +30,8 @@
G_BEGIN_DECLS
/**
- * SECTION:gtypelib
+ * SECTION:gitypelib-internal
+ * @title: GITypelib
* @short_description: Layout and accessors for typelib
* @stability: Stable
*
@@ -42,32 +43,31 @@ G_BEGIN_DECLS
*
* Some of the differences to XPCOM include:
* - Type information is stored not quite as compactly (XPCOM stores it inline
- * in function descriptions in variable-sized blobs of 1 to n bytes. We store
- * 16 bits of type information for each parameter, which is enough to encode
- * simple types inline. Complex (e.g. recursive) types are stored out of line
- * in a separate list of types.
+ * in function descriptions in variable-sized blobs of 1 to n bytes. We store
+ * 16 bits of type information for each parameter, which is enough to encode
+ * simple types inline. Complex (e.g. recursive) types are stored out of line
+ * in a separate list of types.
* - String and complex type data is stored outside of typelib entry blobs,
- * references are stored as offsets relative to the start of the typelib.
- * One possibility is to store the strings and types in a pools at the end
- * of the typelib.
+ * references are stored as offsets relative to the start of the typelib.
+ * One possibility is to store the strings and types in a pools at the end
+ * of the typelib.
*
- * The typelib has the following general format.
+ * The typelib has the following general format:
*
- * typelib ::= header, section-index, directory, blobs, attributes, attributedata
+ * typelib ::= header, section-index, directory, blobs, attributes, attributedata
*
- * directory ::= list of entries
+ * directory ::= list of entries
*
- * entry ::= blob type, name, namespace, offset
- * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
- * attributes ::= list of attributes, sorted by offset
- * attribute ::= offset, key, value
- * attributedata ::= string data for attributes
+ * entry ::= blob type, name, namespace, offset
+ * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
+ * attribute ::= offset, key, value
+ * attributedata ::= string data for attributes
*
* Details
*
* We describe the fragments that make up the typelib in the form of C structs
- * (although some fall short of being valid C structs since they contain multiple
- * flexible arrays).
+ * (although some fall short of being valid C structs since they contain
+ * multiple flexible arrays).
*/
/*
@@ -157,10 +157,11 @@ Changes since 0.1:
* @BLOB_TYPE_OBJECT: An #ObjectBlob
* @BLOB_TYPE_INTERFACE: An #InterfaceBlob
* @BLOB_TYPE_CONSTANT: A #ConstantBlob
+ * @BLOB_TYPE_INVALID_0: Deleted, used to be ErrorDomain.
* @BLOB_TYPE_UNION: A #UnionBlob
*
- * The integral value of this enumeration appears in each "Blob"
- * component of a typelib to identify its type.
+ * The integral value of this enumeration appears in each "Blob" component of
+ * a typelib to identify its type.
*/
typedef enum {
BLOB_TYPE_INVALID,
@@ -173,7 +174,7 @@ typedef enum {
BLOB_TYPE_OBJECT,
BLOB_TYPE_INTERFACE,
BLOB_TYPE_CONSTANT,
- BLOB_TYPE_INVALID_0, /* DELETED - used to be ErrorDomain */
+ BLOB_TYPE_INVALID_0,
BLOB_TYPE_UNION
} GTypelibBlobType;
@@ -188,52 +189,54 @@ typedef enum {
/**
* Header:
* @magic: See #G_IR_MAGIC.
- * @major_version: The version of the typelib format. Minor version changes indicate
- * compatible changes and should still allow the typelib to be parsed
- * by a parser designed for the same major_version.
- * @minor_version: See major_version.
+ * @major_version: The major version number of the typelib format. Major version
+ * number changes indicate incompatible changes to the tyeplib format.
+ * @minor_version: The minor version number of the typelib format. Minor version
+ * number changes indicate compatible changes and should still allow the
+ * typelib to be parsed by a parser designed for the same @major_version.
+ * @reserved: Reserved for future use.
* @n_entries: The number of entries in the directory.
- * @n_local_entries: The number of entries referring to blobs in this typelib. The
- * local entries must occur before the unresolved entries.
+ * @n_local_entries: The number of entries referring to blobs in this typelib.
+ * The local entries must occur before the unresolved entries.
* @directory: Offset of the directory in the typelib.
* @n_attributes: Number of attribute blocks
* @attributes: Offset of the list of attributes in the typelib.
- * @dependencies: Offset of a single string, which is the list of
- * dependencies, separated by the '|' character. The
- * dependencies are required in order to avoid having programs
- * consuming a typelib check for an "Unresolved" type return
- * from every API call.
+ * @dependencies: Offset of a single string, which is the list of dependencies,
+ * separated by the '|' character. The dependencies are required in order
+ * to avoid having programs consuming a typelib check for an "Unresolved"
+ * type return from every API call.
* @size: The size in bytes of the typelib.
* @namespace: Offset of the namespace string in the typelib.
* @nsversion: Offset of the namespace version string in the typelib.
- * @shared_library: This field is the set of shared libraries associated
- * with the typelib. The entries are separated by the '|' (pipe) character.
+ * @shared_library: This field is the set of shared libraries associated with
+ * the typelib. The entries are separated by the '|' (pipe) character.
* @c_prefix: The prefix for the function names of the library
- * @entry_blob_size: The sizes of fixed-size blobs. Recording this information here
- * allows to write parser which continue to work if the format is
- * extended by adding new fields to the end of the fixed-size blobs.
- * @function_blob_size: See above.
- * @callback_blob_size: See above.
- * @signal_blob_size: See above.
- * @vfunc_blob_size: See above.
- * @arg_blob_size: See above.
- * @property_blob_size: See above.
- * @field_blob_size: See above.
- * @value_blob_size: See above.
- * @attribute_blob_size: See above.
- * @constant_blob_size: See above.
- * @object_blob_size: See above.
- * @union_blob_size: See above.
- * @signature_blob_size: See above.
- * @enum_blob_size: See above.
- * @struct_blob_size: See above.
- * @error_domain_blob_size: See above.
- * @interface_blob_size: For variable-size blobs, the size of the struct up to the first
- * flexible array member. Recording this information here allows to
- * write parser which continue to work if the format is extended by
- * adding new fields before the first flexible array member in
- * variable-size blobs.
+ * @entry_blob_size: The sizes of fixed-size blobs. Recording this information
+ * here allows to write parser which continue to work if the format is
+ * extended by adding new fields to the end of the fixed-size blobs.
+ * @function_blob_size: See @entry_blob_size.
+ * @callback_blob_size: See @entry_blob_size.
+ * @signal_blob_size: See @entry_blob_size.
+ * @vfunc_blob_size: See @entry_blob_size.
+ * @arg_blob_size: See @entry_blob_size.
+ * @property_blob_size: See @entry_blob_size.
+ * @field_blob_size: See @entry_blob_size.
+ * @value_blob_size: See @entry_blob_size.
+ * @attribute_blob_size: See @entry_blob_size.
+ * @constant_blob_size: See @entry_blob_size.
+ * @error_domain_blob_size: See @entry_blob_size.
+ * @signature_blob_size: See @entry_blob_size.
+ * @enum_blob_size: See @entry_blob_size.
+ * @struct_blob_size: See @entry_blob_size.
+ * @object_blob_size: See @entry_blob_size.
+ * @interface_blob_size: For variable-size blobs, the size of the struct up to
+ * the first flexible array member. Recording this information here allows
+ * to write parser which continue to work if the format is extended by
+ * adding new fields before the first flexible array member in
+ * variable-size blobs.
+ * @union_blob_size: See @entry_blob_size.
* @sections: Offset of section blob array
+ * @padding: TODO
*
* The header structure appears exactly once at the beginning of a typelib. It is a
* collection of meta-information, such as the number of entries and dependencies.
@@ -242,9 +245,7 @@ typedef struct {
gchar magic[16];
guint8 major_version;
guint8 minor_version;
- /* <private> */
guint16 reserved;
- /* <public> */
guint16 n_entries;
guint16 n_local_entries;
guint32 directory;
@@ -281,10 +282,16 @@ typedef struct {
guint32 sections;
- /* <private> */
guint16 padding[6];
} Header;
+/**
+ * SectionType:
+ * @GI_SECTION_END: TODO
+ * @GI_SECTION_DIRECTORY_INDEX: TODO
+ *
+ * TODO
+ */
typedef enum {
GI_SECTION_END = 0,
GI_SECTION_DIRECTORY_INDEX = 1
@@ -299,7 +306,6 @@ typedef enum {
* and may or may not be present in the typelib. Presently, just used
* for the directory index. This allows a form of dynamic extensibility
* with different tradeoffs from the format minor version.
- *
*/
typedef struct {
guint32 id;
@@ -311,10 +317,11 @@ typedef struct {
* DirEntry:
* @blob_type: A #GTypelibBlobType
* @local: Whether this entry refers to a blob in this typelib.
+ * @reserved: Reserved for future use.
* @name: The name of the entry.
- * @offset: If is_local is set, this is the offset of the blob in the typelib.
- * Otherwise, it is the offset of the namespace in which the blob has
- * to be looked up by name.
+ * @offset: If is_local is set, this is the offset of the blob in the typelib.
+ * Otherwise, it is the offset of the namespace in which the blob has to be
+ * looked up by name.
*
* References to directory entries are stored as 1-based 16-bit indexes.
*
@@ -325,91 +332,100 @@ typedef struct {
guint16 blob_type;
guint16 local : 1;
- /* <private> */
guint16 reserved :15;
- /* <public> */
guint32 name;
guint32 offset;
} DirEntry;
/**
- * SimpleTypeBlob:
- * @is_pointer: Indicates whether the type is passed by reference.
+ * SimpleTypeBlobFlags:
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
+ * @pointer: TODO
+ * @reserved3: Reserved for future use.
* @tag: A #GITypeTag
- * @offset: Offset relative to header->types that points to a TypeBlob.
- * Unlike other offsets, this is in words (ie 32bit units) rather
- * than bytes.
- *
- * The SimpleTypeBlob is the general purpose "reference to a type" construct, used
- * in method parameters, returns, callback definitions, fields, constants, etc.
- * It's actually just a 32 bit integer which you can see from the union definition.
- * This is for efficiency reasons, since there are so many references to types.
- *
- * SimpleTypeBlob is divided into two cases; first, if "reserved" and "reserved2", the
- * type tag for a basic type is embedded in the "tag" bits. This allows e.g.
- * GI_TYPE_TAG_UTF8, GI_TYPE_TAG_INT and the like to be embedded directly without
- * taking up extra space.
*
- * References to "interfaces" (objects, interfaces) are more complicated; In this case,
- * the integer is actually an offset into the directory (see above). Because the header
- * is larger than 2^8=256 bits, all offsets will have one of the upper 24 bits set.
+ * TODO
*/
-typedef union
+typedef struct {
+ guint reserved : 8;
+ guint reserved2 :16;
+ guint pointer : 1;
+ guint reserved3 : 2;
+ guint tag : 5;
+} SimpleTypeBlobFlags;
+
+union _SimpleTypeBlob
{
- struct
- {
- /* <private> */
- guint reserved : 8;
- guint reserved2 :16;
- /* <public> */
- guint pointer : 1;
- /* <private> */
- guint reserved3 : 2;
- /* <public> */
- guint tag : 5;
- } flags;
+ SimpleTypeBlobFlags flags;
guint32 offset;
-} SimpleTypeBlob;
+};
+
+/**
+ * SimpleTypeBlob:
+ * @flags: TODO
+ * @offset: Offset relative to header->types that points to a TypeBlob.
+ * Unlike other offsets, this is in words (ie 32bit units) rather
+ * than bytes.
+ *
+ * The SimpleTypeBlob is the general purpose "reference to a type" construct,
+ * used in method parameters, returns, callback definitions, fields, constants,
+ * etc. It's actually just a 32 bit integer which you can see from the union
+ * definition. This is for efficiency reasons, since there are so many
+ * references to types.
+ *
+ * SimpleTypeBlob is divided into two cases; first, if "reserved" and
+ * "reserved2", the type tag for a basic type is embedded in the "tag" bits.
+ * This allows e.g. GI_TYPE_TAG_UTF8, GI_TYPE_TAG_INT and the like to be
+ * embedded directly without taking up extra space.
+ *
+ * References to "interfaces" (objects, interfaces) are more complicated;
+ * In this case, the integer is actually an offset into the directory (see
+ * above). Because the header is larger than 2^8=256 bits, all offsets will
+ * have one of the upper 24 bits set.
+ */
+typedef union _SimpleTypeBlob SimpleTypeBlob;
/**
* ArgBlob:
* @name: A suggested name for the parameter.
* @in: The parameter is an input to the function
- * @out: The parameter is used to return an output of the function.
- * Parameters can be both in and out. Out parameters implicitly
- * add another level of indirection to the parameter type. Ie if
- * the type is uint32 in an out parameter, the function actually
- * takes an uint32*.
- * @caller_allocates: The parameter is a pointer to a struct or object that will
- * receive an output of the function.
- * @allow_none: Only meaningful for types which are passed as pointers.
- * For an in parameter, indicates if it is ok to pass NULL in, for
- * an out parameter, whether it may return NULL. Note that NULL is a
- * valid GList and GSList value, thus allow_none will normally be set
- * for parameters of these types.
+ * @out: The parameter is used to return an output of the function. Parameters
+ * can be both in and out. Out parameters implicitly add another level of
+ * indirection to the parameter type. Ie if the type is uint32 in an out
+ * parameter, the function actually takes an uint32*.
+ * @caller_allocates: The parameter is a pointer to a struct or object that
+ * will receive an output of the function.
+ * @allow_none: Only meaningful for types which are passed as pointers. For an
+ * in parameter, indicates if it is ok to pass NULL in. Gor an out
+ * parameter, indicates whether it may return NULL. Note that NULL is a
+ * valid GList and GSList value, thus allow_none will normally be set
+ * for parameters of these types.
* @optional: For an out parameter, indicates that NULL may be passed in
- * if the value is not needed.
- * @transfer_ownership: For an in parameter, indicates that the function takes over
- * ownership of the parameter value. For an out parameter, it
- * indicates that the caller is responsible for freeing the return
- * value.
+ * if the value is not needed.
+ * @transfer_ownership: For an in parameter, indicates that the function takes
+ * over ownership of the parameter value. For an out parameter, it indicates
+ * that the caller is responsible for freeing the return value.
* @transfer_container_ownership: For container types, indicates that the
- * ownership of the container, but not of its contents is transferred. This is typically the case
- * for out parameters returning lists of statically allocated things.
- * @return_value: The parameter should be considered the return value of the function.
- * Only out parameters can be marked as return value, and there can be
- * at most one per function call. If an out parameter is marked as
- * return value, the actual return value of the function should be
- * either void or a boolean indicating the success of the call.
- * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes the scope
- * of the user_data and the callback function pointer itself
- * (for languages that emit code at run-time).
- * @closure: Index of the closure (user_data) parameter associated with the callback,
- * or -1.
- * @destroy: Index of the destroy notfication callback parameter associated with
- * the callback, or -1.
- * @arg_type: Describes the type of the parameter. See details below.
+ * ownership of the container, but not of its contents is transferred.
+ * This is typically the case for out parameters returning lists of
+ * statically allocated things.
+ * @return_value: The parameter should be considered the return value of the
+ * function. Only out parameters can be marked as return value, and there
+ * can be at most one per function call. If an out parameter is marked as
+ * return value, the actual return value of the function should be either
+ * void or a boolean indicating the success of the call.
+ * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes
+ * the scope of the user_data and the callback function pointer itself
+ * (for languages that emit code at run-time).
* @skip: Indicates that the parameter is only useful in C and should be skipped.
+ * @reserved: Reserved for future use.
+ * @closure: Index of the closure (user_data) parameter associated with the
+ * callback, or -1.
+ * @destroy: Index of the destroy notfication callback parameter associated
+ * with the callback, or -1.
+ * @padding: TODO
+ * @arg_type: Describes the type of the parameter. See details below.
*
* Types are specified by four bytes. If the three high bytes are zero,
* the low byte describes a basic type, otherwise the 32bit number is an
@@ -428,15 +444,11 @@ typedef struct {
guint return_value : 1;
guint scope : 3;
guint skip : 1;
- /* <private> */
guint reserved :20;
- /* <public> */
- gint8 closure;
- gint8 destroy;
+ gint8 closure;
+ gint8 destroy;
- /* <private> */
- guint16 padding;
- /* <public> */
+ guint16 padding;
SimpleTypeBlob arg_type;
} ArgBlob;
@@ -444,17 +456,21 @@ typedef struct {
/**
* SignatureBlob:
* @return_type: Describes the type of the return value. See details below.
- * @may_return_null: Only relevant for pointer types. Indicates whether the caller
- * must expect NULL as a return value.
- * @caller_owns_return_value: If set, the caller is responsible for freeing the return value
- * if it is no longer needed.
- * @caller_owns_return_container: This flag is only relevant if the return type is a container type.
- * If the flag is set, the caller is resonsible for freeing the
- * container, but not its contents.
- * @skip_return: Indicates that the return value is only useful in C and should be skipped.
- * @n_arguments: The number of arguments that this function expects, also the length
- * of the array of ArgBlobs.
+ * @may_return_null: Only relevant for pointer types. Indicates whether the
+ * caller must expect NULL as a return value.
+ * @caller_owns_return_value: If set, the caller is responsible for freeing
+ * the return value if it is no longer needed.
+ * @caller_owns_return_container: This flag is only relevant if the return type
+ * is a container type. If the flag is set, the caller is resonsible for
+ * freeing the container, but not its contents.
+ * @skip_return: Indicates that the return value is only useful in C and should
+ * be skipped.
+ * @reserved: Reserved for future use.
+ * @n_arguments: The number of arguments that this function expects, also the
+ * length of the array of ArgBlobs.
* @arguments: An array of ArgBlob for the arguments of the function.
+ *
+ * TODO
*/
typedef struct {
SimpleTypeBlob return_type;
@@ -474,43 +490,50 @@ typedef struct {
* CommonBlob:
* @blob_type: A #GTypelibBlobType
* @deprecated: Whether the blob is deprecated.
+ * @reserved: Reserved for future use.
* @name: The name of the blob.
*
* The #CommonBlob is shared between #FunctionBlob,
* #CallbackBlob, #SignalBlob.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type; /* 1 */
guint16 deprecated : 1;
- /* <private> */
guint16 reserved :15;
- /* <public> */
guint32 name;
} CommonBlob;
/**
* FunctionBlob:
- * @blob_Type: #BLOB_TYPE_FUNCTION
- * @symbol: The symbol which can be used to obtain the function pointer with
- * dlsym().
+ * @blob_type: #BLOB_TYPE_FUNCTION
* @deprecated: The function is deprecated.
* @setter: The function is a setter for a property. Language bindings may
- * prefer to not bind individual setters and rely on the generic
- * g_object_set().
+ * prefer to not bind individual setters and rely on the generic
+ * g_object_set().
* @getter: The function is a getter for a property. Language bindings may
- * prefer to not bind individual getters and rely on the generic
- * g_object_get().
- * @constructor:The function acts as a constructor for the object it is contained
- * in.
+ * prefer to not bind individual getters and rely on the generic
+ * g_object_get().
+ * @constructor: The function acts as a constructor for the object it is
+ * contained in.
* @wraps_vfunc: The function is a simple wrapper for a virtual function.
+ * @throws: TODO
* @index: Index of the property that this function is a setter or getter of
- * in the array of properties of the containing interface, or index
- * of the virtual function that this function wraps.
+ * in the array of properties of the containing interface, or index
+ * of the virtual function that this function wraps.
+ * @name: TODO
+ * @symbol: The symbol which can be used to obtain the function pointer with
+ * dlsym().
* @signature: Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ * return value type.
* @is_static: The function is a "static method"; in other words it's a pure
- * function whose name is conceptually scoped to the object.
+ * function whose name is conceptually scoped to the object.
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type; /* 1 */
@@ -537,16 +560,20 @@ typedef struct {
/**
* CallbackBlob:
- * @signature: Offset of the #SignatureBlob describing the parameter types and the
- * return value type.
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @signature: Offset of the #SignatureBlob describing the parameter types and
+ * the return value type.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type; /* 2 */
guint16 deprecated : 1;
- /* <private> */
guint16 reserved :15;
- /* <public> */
guint32 name;
guint32 signature;
} CallbackBlob;
@@ -554,41 +581,52 @@ typedef struct {
/**
* InterfaceTypeBlob:
* @pointer: Whether this type represents an indirection
+ * @reserved: Reserved for future use.
* @tag: A #GITypeTag
+ * @reserved2: Reserved for future use.
* @interface: Index of the directory entry for the interface.
*
* If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
*/
typedef struct {
guint8 pointer :1;
- /* <private> */
guint8 reserved :2;
- /* <public> */
guint8 tag :5;
- /* <private> */
guint8 reserved2;
- /* <public> */
guint16 interface;
} InterfaceTypeBlob;
/**
+ * ArrayTypeDimension:
+ * @length: TODO
+ * @size: TODO
+ *
+ * TODO
+ */
+typedef union {
+ guint16 length;
+ guint16 size;
+} ArrayTypeDimension;
+
+/**
* ArrayTypeBlob:
- * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL
- * value.
- * @has_length: Indicates that length points to a parameter specifying the length
- * of the array. If both has_length and zero_terminated are set, the
- * convention is to pass -1 for the length if the array is
- * zero-terminated.
+ * @pointer: TODO
+ * @reserved: Reserved for future use.
+ * @tag: TODO
+ * @zero_terminated: Indicates that the array must be terminated by a suitable
+ * #NULL value.
+ * @has_length: Indicates that length points to a parameter specifying the
+ * length of the array. If both has_length and zero_terminated are set, the
+ * convention is to pass -1 for the length if the array is zero-terminated.
* @has_size: Indicates that size is the fixed size of the array.
* @array_type: Indicates whether this is a C array, GArray, GPtrArray, or
- * GByteArray. If something other than a C array, the length and element size
- * are implicit in the structure.
- * @length: The index of the parameter which is used to pass the length of the
- * array. The parameter must be an integer type and have the same
- * direction as this one.
- * @size: The fixed size of the array.
- * @type: The type of the array elements.
- * Arrays are passed by reference, thus is_pointer is always 1.
+ * GByteArray. If something other than a C array, the length and element
+ * size are implicit in the structure.
+ * @reserved2: Reserved for future use.
+ * @dimensions: TODO
+ * @type: TODO
+ *
+ * TODO
*/
typedef struct {
guint16 pointer :1;
@@ -601,19 +639,21 @@ typedef struct {
guint16 array_type :2;
guint16 reserved2 :3;
- union {
- guint16 length;
- guint16 size;
- } dimensions;
+ ArrayTypeDimension dimensions;
SimpleTypeBlob type;
} ArrayTypeBlob;
/**
* ParamTypeBlob:
+ * @pointer: TODO
+ * @reserved: Reserved for future use.
+ * @tag: TODO
+ * @reserved2: Reserved for future use.
* @n_types: The number of parameter types to follow.
* @type: Describes the type of the list elements.
*
+ * TODO
*/
typedef struct {
guint8 pointer :1;
@@ -628,6 +668,14 @@ typedef struct {
/**
* ErrorTypeBlob:
+ * @pointer: TODO
+ * @reserved: TODO
+ * @tag: TODO
+ * @reserved2: TODO
+ * @n_domains: TODO: must be 0
+ * @domains: TODO
+ *
+ * TODO
*/
typedef struct {
guint8 pointer :1;
@@ -644,17 +692,16 @@ typedef struct {
* ValueBlob:
* @deprecated: Whether this value is deprecated
* @unsigned_value: if set, value is a 32-bit unsigned integer cast to gint32
- * @value: The numerical value
+ * @reserved: Reserved for future use.
* @name: Name of blob
+ * @value: The numerical value
*
* Values commonly occur in enums and flags.
*/
typedef struct {
guint32 deprecated : 1;
guint32 unsigned_value : 1;
- /* <private> */
guint32 reserved :30;
- /* <public> */
guint32 name;
gint32 value;
} ValueBlob;
@@ -662,15 +709,18 @@ typedef struct {
/**
* FieldBlob:
* @name: The name of the field.
- * @readable:
+ * @readable: TODO
* @writable: How the field may be accessed.
* @has_embedded_type: An anonymous type follows the FieldBlob.
+ * @reserved: Reserved for future use.
* @bits: If this field is part of a bitfield, the number of bits which it
- * uses, otherwise 0.
- * @struct_offset:
- * The offset of the field in the struct. The value 0xFFFF indicates
- * that the struct offset is unknown.
+ * uses, otherwise 0.
+ * @struct_offset: The offset of the field in the struct. The value 0xFFFF
+ * indicates that the struct offset is unknown.
+ * @reserved2: Reserved for future use.
* @type: The type of the field.
+ *
+ * TODO
*/
typedef struct {
guint32 name;
@@ -690,8 +740,16 @@ typedef struct {
/**
* RegisteredTypeBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @unregistered: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
* @gtype_name: The name under which the type is registered with GType.
- * @gtype_init: The symbol name of the get_type() function which registers the type.
+ * @gtype_init: The symbol name of the get_type<!-- -->() function which registers the
+ * type.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -709,16 +767,22 @@ typedef struct {
* @blob_type: #BLOB_TYPE_STRUCT
* @deprecated: Whether this structure is deprecated
* @unregistered: If this is set, the type is not registered with GType.
+ * @is_gtype_struct: Whether this structure is the class or interface layout
+ * for a GObject
* @alignment: The byte boundary that the struct is aligned to in memory
- * @is_gtype_struct: Whether this structure is the class or interface layout for a GObject
* @foreign: If the type is foreign, eg if it's expected to be overridden by
- * a native language binding instead of relying of introspected bindings.
- * @size: The size of the struct in bytes.
+ * a native language binding instead of relying of introspected bindings.
+ * @reserved: Reserved for future use.
+ * @name: TODO
* @gtype_name: String name of the associated #GType
* @gtype_init: String naming the symbol which gets the runtime #GType
- * @n_fields:
- * @fields: An array of n_fields FieldBlobs.
- * should be considered as methods of the struct.
+ * @size: The size of the struct in bytes.
+ * @n_fields: TODO
+ * @n_methods: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -742,29 +806,30 @@ typedef struct {
guint32 reserved2;
guint32 reserved3;
-
-#if 0
- /* variable-length parts of the blob */
- FieldBlob fields[];
- FunctionBlob methods[];
-#endif
} StructBlob;
/**
* UnionBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
* @unregistered: If this is set, the type is not registered with GType.
* @discriminated: Is set if the union is discriminated
* @alignment: The byte boundary that the union is aligned to in memory
- * @size: The size of the union in bytes.
+ * @reserved: Reserved for future use.
+ * @name: TODO
* @gtype_name: String name of the associated #GType
* @gtype_init: String naming the symbol which gets the runtime #GType
+ * @size: TODO
* @n_fields: Length of the arrays
+ * @n_functions: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
* @discriminator_offset: Offset from the beginning of the union where the
- * discriminator of a discriminated union is located.
- * The value 0xFFFF indicates that the discriminator offset
- * is unknown.
+ * discriminator of a discriminated union is located. The value 0xFFFF
+ * indicates that the discriminator offset is unknown.
* @discriminator_type: Type of the discriminator
- * @fields: Array of FieldBlobs describing the alternative branches of the union
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -788,27 +853,25 @@ typedef struct {
gint32 discriminator_offset;
SimpleTypeBlob discriminator_type;
-
-#if 0
- FieldBlob fields[];
- FunctionBlob functions[];
- ConstantBlob discriminator_values[]
-#endif
} UnionBlob;
/**
* EnumBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
* @unregistered: If this is set, the type is not registered with GType.
* @storage_type: The tag of the type used for the enum in the C ABI
- * (will be a signed or unsigned integral type)
+ * (will be a signed or unsigned integral type)
+ * @reserved: Reserved for future use.
+ * @name: TODO
* @gtype_name: String name of the associated #GType
* @gtype_init: String naming the symbol which gets the runtime #GType
- * @error_domain: String naming the #GError domain this enum is
- * associated with
* @n_values: The length of the values array.
* @n_methods: The length of the methods array.
- * @values: Describes the enum values.
- * @methods: Describes the enum methods.
+ * @error_domain: String naming the #GError domain this enum is associated with
+ * @values: TODO
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -829,25 +892,28 @@ typedef struct {
guint32 error_domain;
ValueBlob values[];
-#if 0
- FunctionBlob methods[];
-#endif
} EnumBlob;
/**
* PropertyBlob:
- * @name: The name of the property.
- * @readable:
- * @writable:
- * @construct:
+ * @name: The name of the property.
+ * @deprecated: TODO
+ * @readable: TODO
+ * @writable: TODO
+ * @construct: TODO
* @construct_only: The ParamFlags used when registering the property.
* @transfer_ownership: When writing, the type containing the property takes
- * ownership of the value. When reading, the returned value needs to be released
- * by the caller.
+ * ownership of the value. When reading, the returned value needs to be
+ * released by the caller.
* @transfer_container_ownership: For container types indicates that the
- * ownership of the container, but not of its contents, is transferred. This is
- * typically the case when reading lists of statically allocated things.
+ * ownership of the container, but not of its contents, is transferred.
+ * This is typically the case when reading lists of statically allocated
+ * things.
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
* @type: Describes the type of the property.
+ *
+ * TODO
*/
typedef struct {
guint32 name;
@@ -868,20 +934,25 @@ typedef struct {
/**
* SignalBlob:
- * @name: The name of the signal.
- * @run_first:
- * @run_last:
- * @run_cleanup:
- * @no_recurse:
- * @detailed:
- * @action:
+ * @deprecated: TODO
+ * @run_first: TODO
+ * @run_last: TODO
+ * @run_cleanup: TODO
+ * @no_recurse: TODO
+ * @detailed: TODO
+ * @action: TODO
* @no_hooks: The flags used when registering the signal.
* @has_class_closure: Set if the signal has a class closure.
* @true_stops_emit: Whether the signal has true-stops-emit semantics
- * @class_closure: The index of the class closure in the list of virtual functions
- * of the object or interface on which the signal is defined.
- * @signature: Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ * @reserved: Reserved for future use.
+ * @class_closure: The index of the class closure in the list of virtual
+ * functions of the object or interface on which the signal is defined.
+ * @name: The name of the signal.
+ * @reserved2: Reserved for future use.
+ * @signature: Offset of the SignatureBlob describing the parameter types
+ * and the return value type.
+ *
+ * TODO
*/
typedef struct {
guint16 deprecated : 1;
@@ -909,19 +980,28 @@ typedef struct {
* VFuncBlob:
* @name: The name of the virtual function.
* @must_chain_up: If set, every implementation of this virtual function must
- * chain up to the implementation of the parent class.
- * @must_be_implemented: If set, every derived class must override this virtual function.
- * @must_not_be_implemented: If set, derived class must not override this virtual function.
- * @class_closure: Set if this virtual function is the class closure of a signal.
+ * chain up to the implementation of the parent class.
+ * @must_be_implemented: If set, every derived class must override this virtual
+ * function.
+ * @must_not_be_implemented: If set, derived class must not override this
+ * virtual function.
+ * @class_closure: Set if this virtual function is the class closure of a
+ * signal.
+ * @throws: TODO
+ * @reserved: Reserved for future use.
* @signal: The index of the signal in the list of signals of the object or
- * interface to which this virtual function belongs.
- * @struct_offset: The offset of the function pointer in the class struct. The value
- * 0xFFFF indicates that the struct offset is unknown.
- * @invoker: If a method invoker for this virtual exists, this is the offset in the
- * class structure of the method. If no method is known, this value will be 0x3ff.
- * @signature:
- * Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ * interface to which this virtual function belongs.
+ * @struct_offset: The offset of the function pointer in the class struct.
+ * The value 0xFFFF indicates that the struct offset is unknown.
+ * @invoker: If a method invoker for this virtual exists, this is the offset
+ * in the class structure of the method. If no method is known, this value
+ * will be 0x3ff.
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ * @signature: Offset of the SignatureBlob describing the parameter types and
+ * the return value type.
+ *
+ * TODO
*/
typedef struct {
guint32 name;
@@ -945,36 +1025,41 @@ typedef struct {
/**
* ObjectBlob:
* @blob_type: #BLOB_TYPE_OBJECT
+ * @deprecated: TODO
+ * @abstract: TODO
* @fundamental: this object is not a GObject derived type, instead it's
- * an additional fundamental type.
+ * an additional fundamental type.
+ * @reserved: Reserved for future use.
+ * @name: TODO
* @gtype_name: String name of the associated #GType
* @gtype_init: String naming the symbol which gets the runtime #GType
* @parent: The directory index of the parent type. This is only set for
- * objects. If an object does not have a parent, it is zero.
- * @n_interfaces:
- * @n_fields:
- * @n_properties:
- * @n_methods:
- * @n_signals:
- * @n_vfuncs:
- * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted
- * between the arrays to ensure that they start on a 32bit boundary.
- * @interfaces: An array of indices of directory entries for the implemented
- * interfaces.
- * @fields: Describes the fields.
- * @methods: Describes the methods, constructors, setters and getters.
- * @properties: Describes the properties.
- * @signals: Describes the signals.
- * @vfuncs: Describes the virtual functions.
- * @constants: Describes the constants.
+ * objects. If an object does not have a parent, it is zero.
+ * @gtype_struct: TODO
+ * @n_interfaces: TODO
+ * @n_fields: TODO
+ * @n_properties: TODO
+ * @n_methods: TODO
+ * @n_signals: TODO
+ * @n_vfuncs: TODO
+ * @n_constants: The lengths of the arrays.Up to 16bits of padding may be
+ * inserted between the arrays to ensure that they start on a 32bit
+ * boundary.
+ * @reserved2: Reserved for future use.
* @ref_func: String pointing to a function which can be called to increase
- * the reference count for an instance of this object type.
+ * the reference count for an instance of this object type.
* @unref_func: String pointing to a function which can be called to decrease
- * the reference count for an instance of this object type.
+ * the reference count for an instance of this object type.
* @set_value_func: String pointing to a function which can be called to
- * convert a pointer of this object to a GValue
+ * convert a pointer of this object to a GValue
* @get_value_func: String pointing to a function which can be called to
- * convert extract a pointer to this object from a GValue
+ * convert extract a pointer to this object from a GValue
+ * @reserved3: Reserved for future use.
+ * @reserved4: Reserved for future use.
+ * @interfaces: An array of indices of directory entries for the implemented
+ * interfaces.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type; /* 7 */
@@ -1008,35 +1093,32 @@ typedef struct {
guint32 reserved4;
guint16 interfaces[];
-
-#if 0
- /* variable-length parts of the blob */
- FieldBlob fields[];
- PropertyBlob properties[];
- FunctionBlob methods[];
- SignalBlob signals[];
- VFuncBlob vfuncs[];
- ConstantBlob constants[];
-#endif
} ObjectBlob;
/**
* InterfaceBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @gtype_name: TODO
+ * @gtype_init: TODO
* @gtype_struct: Name of the interface "class" C structure
* @n_prerequisites: Number of prerequisites
* @n_properties: Number of properties
* @n_methods: Number of methods
* @n_signals: Number of signals
* @n_vfuncs: Number of virtual functions
- * @n_constants: The lengths of the arrays.
- * Up to 16bits of padding may be inserted between the arrays to ensure that they
- * start on a 32bit boundary.
- * @prerequisites: An array of indices of directory entries for required interfaces.
- * @methods: Describes the methods, constructors, setters and getters.
- * @properties: Describes the properties.
- * @signals: Describes the signals.
- * @vfuncs: Describes the virtual functions.
- * @constants: Describes the constants.
+ * @n_constants: The lengths of the arrays. Up to 16bits of padding may be
+ * inserted between the arrays to ensure that they start on a 32bit
+ * boundary.
+ * @padding: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ * @prerequisites: An array of indices of directory entries for required
+ * interfaces.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -1061,23 +1143,21 @@ typedef struct {
guint32 reserved3;
guint16 prerequisites[];
-
-#if 0
- /* variable-length parts of the blob */
- PropertyBlob properties[];
- FunctionBlob methods[];
- SignalBlob signals[];
- VFuncBlob vfuncs[];
- ConstantBlob constants[];
-#endif
} InterfaceBlob;
/**
* ConstantBlob:
- * @type: The type of the value. In most cases this should be a numeric
- * type or string.
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @type: The type of the value. In most cases this should be a numeric type
+ * or string.
* @size: The size of the value in bytes.
* @offset: The offset of the value in the typelib.
+ * @reserved2: Reserved for future use.
+ *
+ * TODO
*/
typedef struct {
guint16 blob_type;
@@ -1096,10 +1176,12 @@ typedef struct {
/**
* AttributeBlob:
* @offset: The offset of the typelib entry to which this attribute refers.
- * Attributes are kept sorted by offset, so that the attributes
- * of an entry can be found by a binary search.
+ * Attributes are kept sorted by offset, so that the attributes of an
+ * entry can be found by a binary search.
* @name: The name of the attribute, a string.
* @value: The value of the attribute (also a string)
+ *
+ * TODO
*/
typedef struct {
guint32 offset;
@@ -1107,9 +1189,6 @@ typedef struct {
guint32 value;
} AttributeBlob;
-/**
- * GITypelib:
- */
struct _GITypelib {
/* <private> */
guchar *data;
@@ -1137,6 +1216,15 @@ gboolean g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
void g_typelib_check_sanity (void);
+/**
+ * g_typelib_get_string:
+ * @typelib: TODO
+ * @offset: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
#define g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)])
@@ -1159,6 +1247,11 @@ typedef enum
G_TYPELIB_ERROR_INVALID_BLOB
} GITypelibError;
+/**
+ * G_TYPELIB_ERROR:
+ *
+ * TODO
+ */
#define G_TYPELIB_ERROR (g_typelib_error_quark ())
GQuark g_typelib_error_quark (void);
@@ -1171,6 +1264,11 @@ gboolean g_typelib_validate (GITypelib *typelib,
AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info,
guint32 blob_offset);
+/**
+ * GITypelibHashBuilder:
+ *
+ * TODO
+ */
typedef struct _GITypelibHashBuilder GITypelibHashBuilder;
GITypelibHashBuilder * _gi_typelib_hash_builder_new (void);
diff --git a/girepository/gitypelib.c b/girepository/gitypelib.c
index 1436caf..8883496 100644
--- a/girepository/gitypelib.c
+++ b/girepository/gitypelib.c
@@ -130,6 +130,15 @@ get_type_blob (GITypelib *typelib,
return (InterfaceTypeBlob*) get_blob (typelib, simple->offset, error);
}
+/**
+ * g_typelib_get_dir_entry:
+ * @typelib: TODO
+ * @index: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
DirEntry *
g_typelib_get_dir_entry (GITypelib *typelib,
guint16 index)
@@ -159,6 +168,15 @@ get_section_by_id (GITypelib *typelib,
return NULL;
}
+/**
+ * g_typelib_get_dir_entry_by_name:
+ * @typelib: TODO
+ * @name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
DirEntry *
g_typelib_get_dir_entry_by_name (GITypelib *typelib,
const char *name)
@@ -196,6 +214,15 @@ g_typelib_get_dir_entry_by_name (GITypelib *typelib,
}
}
+/**
+ * g_typelib_get_dir_entry_by_gtype_name:
+ * @typelib: TODO
+ * @gtype_name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
DirEntry *
g_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib,
const gchar *gtype_name)
@@ -281,6 +308,15 @@ strsplit_iter_clear (StrSplitIter *iter)
g_free (iter->buf.str);
}
+/**
+ * g_typelib_matches_gtype_name_prefix:
+ * @typelib: TODO
+ * @gtype_name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
gboolean
g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
const gchar *gtype_name)
@@ -326,6 +362,15 @@ g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
return ret;
}
+/**
+ * g_typelib_get_dir_entry_by_error_domain:
+ * @typelib: TODO
+ * @error_domain: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
DirEntry *
g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
GQuark error_domain)
@@ -356,6 +401,11 @@ g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
return NULL;
}
+/**
+ * g_typelib_check_sanity:
+ *
+ * TODO
+ */
void
g_typelib_check_sanity (void)
{
@@ -2089,6 +2139,15 @@ prefix_with_context (GError **error,
g_free (buf);
}
+/**
+ * g_typelib_validate:
+ * @typelib: TODO
+ * @error: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
gboolean
g_typelib_validate (GITypelib *typelib,
GError **error)
@@ -2118,6 +2177,13 @@ g_typelib_validate (GITypelib *typelib,
return TRUE;
}
+/**
+ * g_typelib_error_quark:
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
GQuark
g_typelib_error_quark (void)
{
@@ -2271,8 +2337,8 @@ _g_typelib_ensure_open (GITypelib *typelib)
* pointed to by @typelib will be automatically g_free()d when the
* repository is destroyed.
*
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
GITypelib *
g_typelib_new_from_memory (guint8 *memory,
gsize len,
@@ -2300,8 +2366,8 @@ g_typelib_new_from_memory (guint8 *memory,
*
* Creates a new #GITypelib from a memory location.
*
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
GITypelib *
g_typelib_new_from_const_memory (const guchar *memory,
gsize len,
@@ -2328,8 +2394,8 @@ g_typelib_new_from_const_memory (const guchar *memory,
*
* Creates a new #GITypelib from a #GMappedFile.
*
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
GITypelib *
g_typelib_new_from_mapped_file (GMappedFile *mfile,
GError **error)
@@ -2355,7 +2421,7 @@ g_typelib_new_from_mapped_file (GMappedFile *mfile,
* @typelib: a #GITypelib
*
* Free a #GITypelib.
- **/
+ */
void
g_typelib_free (GITypelib *typelib)
{
@@ -2372,6 +2438,14 @@ g_typelib_free (GITypelib *typelib)
g_slice_free (GITypelib, typelib);
}
+/**
+ * g_typelib_get_namespace:
+ * @typelib: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
const gchar *
g_typelib_get_namespace (GITypelib *typelib)
{
@@ -2386,8 +2460,8 @@ g_typelib_get_namespace (GITypelib *typelib)
*
* Loads a symbol from #GITypelib.
*
- * Return value: #TRUE on success
- **/
+ * Returns: #TRUE on success
+ */
gboolean
g_typelib_symbol (GITypelib *typelib, const char *symbol_name, gpointer *symbol)
{
diff --git a/girepository/gitypelib.h b/girepository/gitypelib.h
index 52c5c40..0726bf1 100644
--- a/girepository/gitypelib.h
+++ b/girepository/gitypelib.h
@@ -31,6 +31,19 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gitypelib
+ * @title: gitypelib
+ * @short_description: TODO
+ *
+ * TODO
+ */
+
+/**
+ * GITypelib:
+ *
+ * TODO
+ */
typedef struct _GITypelib GITypelib;
GITypelib * g_typelib_new_from_memory (guint8 *memory,
diff --git a/girepository/gitypes.h b/girepository/gitypes.h
index 660a98f..cb8cb34 100644
--- a/girepository/gitypes.h
+++ b/girepository/gitypes.h
@@ -29,7 +29,9 @@
G_BEGIN_DECLS
+#ifndef __GTK_DOC_IGNORE__
typedef struct _GIBaseInfoStub GIBaseInfo;
+#endif
/**
* GICallableInfo:
@@ -47,6 +49,25 @@ typedef GIBaseInfo GICallableInfo;
typedef GIBaseInfo GIFunctionInfo;
/**
+ * SECTION:gicallbackinfo
+ * @title: GICallbackInfo
+ * @short_description: Struct representing a callback
+ *
+ * GICallbackInfo represents a callback.
+ *
+ * <refsect1 id="gi-gicallbackinfo.struct-hierarchy" role="struct_hierarchy">
+ * <title role="struct_hierarchy.title">Struct hierarchy</title>
+ * <synopsis>
+ * <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ * +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
+ * +----GIFunctionInfo
+ * +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
+ * +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
+ * </synopsis>
+ * </refsect1>
+ */
+
+/**
* GICallbackInfo:
*
* Represents a callback, eg arguments and return value.
@@ -103,6 +124,22 @@ typedef GIBaseInfo GIInterfaceInfo;
typedef GIBaseInfo GIConstantInfo;
/**
+ * SECTION:givalueinfo
+ * @title: GIValueInfo
+ * @short_description: Struct representing a value
+ *
+ * GIValueInfo represents a value.
+ *
+ * <refsect1 id="gi-givalueinfo.struct-hierarchy" role="struct_hierarchy">
+ * <title role="struct_hierarchy.title">Struct hierarchy</title>
+ * <synopsis>
+ * <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ * +----GIValueInfo
+ * </synopsis>
+ * </refsect1>
+ */
+
+/**
* GIValueInfo:
*
* Represents a enum value of a #GIEnumInfo.
@@ -158,12 +195,7 @@ typedef GIBaseInfo GITypeInfo;
*/
typedef struct _GIUnresolvedInfo GIUnresolvedInfo;
-/**
- * GIArgument:
- *
- * Stores an argument of varying type
- */
-typedef union
+union _GIArgument
{
gboolean v_boolean;
gint8 v_int8;
@@ -186,7 +218,35 @@ typedef union
gsize v_size;
gchar * v_string;
gpointer v_pointer;
-} GIArgument;
+};
+
+/**
+ * GIArgument:
+ * @v_boolean: TODO
+ * @v_int8: TODO
+ * @v_uint8: TODO
+ * @v_int16: TODO
+ * @v_uint16: TODO
+ * @v_int32: TODO
+ * @v_uint32: TODO
+ * @v_int64: TODO
+ * @v_uint64: TODO
+ * @v_float: TODO
+ * @v_double: TODO
+ * @v_short: TODO
+ * @v_ushort: TODO
+ * @v_int: TODO
+ * @v_uint: TODO
+ * @v_long: TODO
+ * @v_ulong: TODO
+ * @v_ssize: TODO
+ * @v_size: TODO
+ * @v_string: TODO
+ * @v_pointer: TODO
+ *
+ * Stores an argument of varying type
+ */
+typedef union _GIArgument GIArgument;
/**
* GIInfoType:
@@ -200,6 +260,7 @@ typedef union
* @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo
* @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo
* @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo
+ * @GI_INFO_TYPE_INVALID_0: deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN.
* @GI_INFO_TYPE_UNION: union, see #GIUnionInfo
* @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo
* @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo
@@ -209,7 +270,7 @@ typedef union
* @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo
* @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo
* @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
- * the typelib, or any of its dependencies.
+ * the typelib, or any of its dependencies.
*
* The type of a GIBaseInfo struct.
*/
@@ -225,7 +286,7 @@ typedef enum
GI_INFO_TYPE_OBJECT,
GI_INFO_TYPE_INTERFACE,
GI_INFO_TYPE_CONSTANT,
- GI_INFO_TYPE_INVALID_0, /* 10 */ /* DELETED - used to be ERROR_DOMAIN */
+ GI_INFO_TYPE_INVALID_0, /* 10 */
GI_INFO_TYPE_UNION,
GI_INFO_TYPE_VALUE,
GI_INFO_TYPE_SIGNAL,
@@ -319,17 +380,17 @@ typedef enum {
* @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
* @GI_TYPE_TAG_FLOAT: float
* @GI_TYPE_TAG_DOUBLE: double floating point
- * @GI_TYPE_TAG_UNICHAR: Unicode character
* @GI_TYPE_TAG_GTYPE: a #GType
* @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
* @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
- * as the native filesystem is using.
+ * as the native filesystem is using.
* @GI_TYPE_TAG_ARRAY: an array
* @GI_TYPE_TAG_INTERFACE: an extended interface object
* @GI_TYPE_TAG_GLIST: a #GList
* @GI_TYPE_TAG_GSLIST: a #GSList
* @GI_TYPE_TAG_GHASH: a #GHashTable
* @GI_TYPE_TAG_ERROR: a #GError
+ * @GI_TYPE_TAG_UNICHAR: Unicode character
*
* The type tag of a #GITypeInfo.
*/
@@ -359,12 +420,17 @@ typedef enum {
GI_TYPE_TAG_ERROR = 20,
/* Another basic type */
GI_TYPE_TAG_UNICHAR = 21
- /* Note - there is only room currently for 32 tags.
- * See docs/typelib-format.txt SimpleTypeBlob definition */
+ /* Note - there is currently only room for 32 tags */
} GITypeTag;
+/**
+ * GI_TYPE_TAG_N_TYPES:
+ *
+ * TODO
+ */
#define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
+#ifndef __GTK_DOC_IGNORE__
/* These were removed and no longer appear in the typelib;
* instead, the machine-specific versions like INT32 are
* always used.
@@ -372,6 +438,7 @@ typedef enum {
#define GI_TYPE_TAG_SHORT GI_TYPE_TAG_SHORT_WAS_REMOVED
#define GI_TYPE_TAG_INT GI_TYPE_TAG_INT_WAS_REMOVED
#define GI_TYPE_TAG_LONG GI_TYPE_TAG_LONG_WAS_REMOVED
+#endif
/**
* GIArrayType:
@@ -442,10 +509,12 @@ typedef enum
} GIFunctionInfoFlags;
#ifndef __GI_SCANNER__
+#ifndef __GTK_DOC_IGNORE__
/* backwards compatibility */
typedef GIArgument GArgument;
typedef struct _GITypelib GTypelib;
#endif
+#endif
G_END_DECLS
diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c
index 95b7112..8ae1e91 100644
--- a/girepository/giunioninfo.c
+++ b/girepository/giunioninfo.c
@@ -28,8 +28,8 @@
/**
* SECTION:giunioninfo
- * @Short_description: Struct representing a union.
- * @Title: GIUnionInfo
+ * @title: GIUnionInfo
+ * @short_description: Struct representing a union.
*
* GIUnionInfo represents a union type.
*
@@ -147,7 +147,7 @@ g_union_info_is_discriminated (GIUnionInfo *info)
}
/**
- * g_union_info_get_discrimintor_offset:
+ * g_union_info_get_discriminator_offset:
* @info: a #GIUnionInfo
*
* Returns offset of the discriminator field in the structure.
diff --git a/girepository/giunioninfo.h b/girepository/giunioninfo.h
index 83696f7..5359346 100644
--- a/girepository/giunioninfo.h
+++ b/girepository/giunioninfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_UNION_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIUnionInfo.
+ */
#define GI_IS_UNION_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_UNION)
diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c
index 9d6ea39..eaf523d 100644
--- a/girepository/givfuncinfo.c
+++ b/girepository/givfuncinfo.c
@@ -30,8 +30,8 @@
/**
* SECTION:givfuncinfo
- * @Short_description: Struct representing a virtual function
- * @Title: GIVFuncInfo
+ * @title: GIVFuncInfo
+ * @short_description: Struct representing a virtual function
*
* GIVfuncInfo represents a virtual function. A property belongs to
* either a #GIObjectInfo or a #GIInterfaceInfo.
diff --git a/girepository/givfuncinfo.h b/girepository/givfuncinfo.h
index d8a8533..f22517a 100644
--- a/girepository/givfuncinfo.h
+++ b/girepository/givfuncinfo.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
+/**
+ * GI_IS_VFUNC_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIVfuncInfo.
+ */
#define GI_IS_VFUNC_INFO(info) \
(g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_VFUNC)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
