diff options
| author | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-10-10 22:21:18 +0200 |
|---|---|---|
| committer | Colin Walters <walters@verbum.org> | 2013-10-10 16:48:51 -0400 |
| commit | a737daa16e458e87f189c2535f11f4bd2dde8f1a (patch) | |
| tree | aeafe6e33e0009a261262219f2286aab248a2ae6 | |
| parent | 3c01854fe58c845956bc8f08e9bd9fd9929b6f8d (diff) | |
| download | gobject-introspection-a737daa16e458e87f189c2535f11f4bd2dde8f1a.tar.gz | |
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
59 files changed, 1864 insertions, 938 deletions
@@ -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 04ec549c..c91c41c9 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 \ @@ -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 1f78408f..07bdb46c 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 937ac808..d3b3f930 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.sgml b/docs/reference/gi-docs.sgml deleted file mode 100644 index 2f8bf861..00000000 --- a/docs/reference/gi-docs.sgml +++ /dev/null @@ -1,83 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ -<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> -<!ENTITY version SYSTEM "version.xml"> -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>GObject Introspection Reference Manual</title> - </bookinfo> - - <chapter id="glib"> - <title>GObject-Introspection Overview</title> - <para> -Bla bla bla bla bla - </para> - <xi:include href="gi-overview.xml"/> -<!-- - &gi-building; ---> - </chapter> - -<!-- - <chapter id="tools"> - <title>GObject Introspection Tools</title> - - &g-ir-scanner; - &g-ir-compiler; - &g-ir-generator; - </chapter> ---> - - <part id="girepository"> - <chapter id="gi-libgirepository"> - <title>GIRepository</title> - <xi:include href="xml/girepository.xml"/> - </chapter> - <chapter id="gi-ffi"> - <title>GIR Foreign functions interface</title> - <xi:include href="xml/girffi.xml"/> - </chapter> - <chapter id="gi-repository-structs"> - <title>GIRepository structs</title> - <xi:include href="gi-struct-hierarchy.xml"/> - <xi:include href="xml/gibaseinfo.xml"/> - <xi:include href="xml/gifunctioninfo.xml"/> - <xi:include href="xml/gicallableinfo.xml"/> - <xi:include href="xml/giarginfo.xml"/> - <xi:include href="xml/gitypeinfo.xml"/> - <xi:include href="xml/gistructinfo.xml"/> - <xi:include href="xml/giunioninfo.xml"/> - <xi:include href="xml/gifieldinfo.xml"/> - <xi:include href="xml/gipropertyinfo.xml"/> - <xi:include href="xml/givfuncinfo.xml"/> - <xi:include href="xml/gisignalinfo.xml"/> - <xi:include href="xml/gienuminfo.xml"/> - <xi:include href="xml/giregisteredtypeinfo.xml"/> - <xi:include href="xml/giobjectinfo.xml"/> - <xi:include href="xml/giinterfaceinfo.xml"/> - <xi:include href="xml/giconstantinfo.xml"/> - <xi:include href="xml/gierrordomaininfo.xml"/> - </chapter> - - </part> - - - <part id="gi-gir"> - <title>GIR markup format</title> - <xi:include href="gi-gir-reference.xml" /> -<!-- - &gi-gir-creating; - &gi-gir-parsing; - &gi-gir-verifying; ---> - </part> - - <chapter id="gi-typelib"> - <title>Typelib binary format</title> - <xi:include href="xml/gtypelib.xml" /> - </chapter> - - <xi:include href="xml/annotation-glossary.xml" /> -</book> diff --git a/docs/reference/gi-docs.xml b/docs/reference/gi-docs.xml new file mode 100644 index 00000000..b6bc54f1 --- /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 8d19112e..fb97984f 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-gir.sgml b/docs/reference/gi-gir.sgml deleted file mode 100644 index 590444ff..00000000 --- a/docs/reference/gi-gir.sgml +++ /dev/null @@ -1,23 +0,0 @@ -<chapter id="gi-gir-reference"> - - <title>The GIR XML format</title> - - <para> - This chapter describes the GIR XML markup format. - </para> - - <section id="gi-gir-api"> - <title>API node</title> - - The root node of all GIR documents is the api node. - - Attributes: - <itemizedlist> - <listitem><para>version</para></listitem> - The version of the GIR, currently the only known version is 1.0. - </itemizedlist> - - </section> - -</chapter> - diff --git a/docs/reference/gi-overview.xml b/docs/reference/gi-overview.xml deleted file mode 100644 index 0943b8e5..00000000 --- a/docs/reference/gi-overview.xml +++ /dev/null @@ -1,52 +0,0 @@ -<?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-overview"> -<refmeta> - <refentrytitle role="top_of_page" id="gi-overview.top_of_page">Introspection Overview</refentrytitle> - <manvolnum>3</manvolnum> - <refmiscinfo>GI Library</refmiscinfo> -</refmeta> -<refnamediv> - <refname>Overview</refname> - <refpurpose>General overview of introspection</refpurpose> -</refnamediv> - -<refsynopsisdiv> -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>A quick overview how the different components fits together:</para> - -<inlinegraphic fileref="overview.png" format="PNG"></inlinegraphic> - -</refsynopsisdiv> - -</refentry> diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt index 8b880cf8..59f0d50a 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 eea51282..1407485f 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/gi.types b/docs/reference/gi.types deleted file mode 100644 index 3b4e9df6..00000000 --- a/docs/reference/gi.types +++ /dev/null @@ -1,2 +0,0 @@ -g_irepository_get_type -g_irepository_get_type diff --git a/docs/reference/overview-building.xml b/docs/reference/overview-building.xml new file mode 100644 index 00000000..7c843ce3 --- /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 00000000..6511d4b7 --- /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 d1cc3c74..fefbcc3d 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 00000000..a4798c41 --- /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 d61f4be2..572839c3 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 3f4163e3..4045ab9c 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 37893e6c..4bbe850a 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 54c8ee4f..a49dd506 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 28c5950e..e69e3e9d 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 a7d7079a..71f9d0c6 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 88220b4e..7b2f716c 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 2bbf9569..2ce1dcad 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 400a56d6..253ec684 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 0b9a9e1b..257e4c12 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 1d9a20dd..2bbc0214 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 4ca54093..56a2e22e 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 a5858c76..ecd61275 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 7a9ecae0..7987c926 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 f998da44..481fc54e 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 ce40cda7..ec33a630 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 5c0ace4c..6eba9fcc 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 7ba2a93b..b0aff37c 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 ee4b8a82..06206776 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 61316cb9..77a11cb8 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 14b18b41..7644664b 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 6e3d31e2..e45e0603 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 d46d738b..e5db25b4 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 93c23728..6fc7c77e 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 2b2b1713..dea250df 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 f4c80eaa..30642fe1 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 56caff73..50cabb17 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 368332ea..84278b89 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 f4110c38..be75276e 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 e3a1e4a4..8502610c 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 dc17e322..f205e7cf 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 1d10708e..4300534d 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 a43fbc1b..3c17f564 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 ef834b12..7591799a 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 ac71008d..23f4d625 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 1436caf1..8883496e 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 52c5c400..0726bf19 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 660a98f9..cb8cb344 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 95b71123..8ae1e915 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 83696f76..5359346a 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 9d6ea39d..eaf523d2 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 d8a8533b..f22517a6 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) |