GNOME.org
 

[libgxps] docs: Add API docs

commit 40e7c583543b9b57ddd1e74541fda0771b5ac06f
Author: Carlos Garcia Campos <carlosgc gnome org>
Date:   Sat Oct 8 16:20:40 2011 +0200

    docs: Add API docs

 Makefile.am                         |    6 ++
 TODO                                |    1 -
 configure.ac                        |    6 ++
 docs/Makefile.am                    |    1 +
 docs/reference/Makefile.am          |   87 ++++++++++++++++++++++
 docs/reference/libgxps-docs.sgml    |   30 ++++++++
 docs/reference/libgxps-sections.txt |  137 +++++++++++++++++++++++++++++++++++
 docs/reference/version.xml.in       |    1 +
 libgxps/gxps-document-structure.c   |  102 ++++++++++++++++++++++++++
 libgxps/gxps-document-structure.h   |   14 ++++
 libgxps/gxps-document.c             |   63 ++++++++++++++++
 libgxps/gxps-document.h             |    7 ++
 libgxps/gxps-error.c                |    6 ++
 libgxps/gxps-error.h                |   15 ++++
 libgxps/gxps-file.c                 |   57 +++++++++++++++
 libgxps/gxps-file.h                 |   20 +++++
 libgxps/gxps-links.c                |   95 ++++++++++++++++++++++++
 libgxps/gxps-links.h                |   11 +++
 libgxps/gxps-page.c                 |   60 +++++++++++++++
 libgxps/gxps-page.h                 |   22 ++++++
 20 files changed, 740 insertions(+), 1 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index b2c2fbb..50878b4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,6 +4,8 @@ if ENABLE_TEST
 SUBDIRS += test
 endif
 
+SUBDIRS += docs
+
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libgxps.pc
 
@@ -12,3 +14,7 @@ EXTRA_DIST = \
 
 DISTCLEANFILES = \
 	$(pkgconfig_DATA)
+
+DISTCHECK_CONFIGURE_FLAGS = 	\
+	--enable-gtk-doc	\
+	--disable-maintainer-mode
\ No newline at end of file
diff --git a/TODO b/TODO
index dc19fbb..6ed0d19 100644
--- a/TODO
+++ b/TODO
@@ -1,7 +1,6 @@
 General
 -------
 
-- Gtk-doc
 - GObject Introspection
 - Version API (Check macros)
 - Tools: xps2ps, xps2pdf, xps2html, ...
diff --git a/configure.ac b/configure.ac
index 3f3c9e5..772b140 100644
--- a/configure.ac
+++ b/configure.ac
@@ -147,6 +147,9 @@ fi
 
 AM_CONDITIONAL(ENABLE_TEST, test x$enable_test = xyes)
 
+dnl gtk-doc
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+
 # **********
 # Versioning
 # **********
@@ -166,6 +169,9 @@ Makefile
 libgxps.pc
 libgxps/Makefile
 test/Makefile
+docs/Makefile
+docs/reference/Makefile
+docs/reference/version.xml
 ])
 
 AC_OUTPUT
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..b69bfe0
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = reference
\ No newline at end of file
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..e38b177
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,87 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=libgxps
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../../libgxps
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml --source-suffixes=c,h --name-space=gxps
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# 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)/libgxps/*.h
+CFILE_GLOB=$(top_srcdir)/libgxps/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# 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=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
+expand_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. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=				\
+	-I$(top_srcdir)/libgxps		\
+	-I$(top_builddir)/libgxps	\
+	$(GXPS_CFLAGS)
+
+GTKDOC_LIBS=					\
+	$(top_builddir)/libgxps/libgxps.la	\
+	$(GXPS_LIBS)				\
+	$(LIBJPEG)				\
+	$(LIBTIFF)
+
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += version.xml.in
diff --git a/docs/reference/libgxps-docs.sgml b/docs/reference/libgxps-docs.sgml
new file mode 100644
index 0000000..d945a10
--- /dev/null
+++ b/docs/reference/libgxps-docs.sgml
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <bookinfo>
+    <title>GXPS Reference Manual</title>
+    <releaseinfo>
+      for libgxps &version;
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>GXPS</title>
+    <xi:include href="xml/gxps-file.xml"/>
+    <xi:include href="xml/gxps-document.xml"/>
+    <xi:include href="xml/gxps-page.xml"/>
+    <xi:include href="xml/gxps-links.xml"/>
+    <xi:include href="xml/gxps-document-structure.xml"/>
+    <xi:include href="xml/gxps-error.xml"/>
+  </chapter>
+
+  <index id="api-index-full">
+    <title>Index of all symbols</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
diff --git a/docs/reference/libgxps-sections.txt b/docs/reference/libgxps-sections.txt
new file mode 100644
index 0000000..4745bd9
--- /dev/null
+++ b/docs/reference/libgxps-sections.txt
@@ -0,0 +1,137 @@
+<INCLUDE>libgxps/gxps.h</INCLUDE>
+
+<SECTION>
+<FILE>gxps-file</FILE>
+<TITLE>GXPSFile</TITLE>
+GXPSFile
+GXPS_FILE_ERROR
+GXPSFileError
+gxps_file_new
+gxps_file_get_n_documents
+gxps_file_get_document
+gxps_file_get_document_for_link_target
+
+<SUBSECTION Standard>
+GXPS_TYPE_FILE
+GXPS_FILE
+GXPS_FILE_CLASS
+GXPS_IS_FILE
+GXPS_IS_FILE_CLASS
+GXPS_FILE_GET_CLASS
+
+<SUBSECTION Private>
+gxps_file_get_type
+gxps_file_error_quark
+</SECTION>
+
+<SECTION>
+<FILE>gxps-document</FILE>
+<TITLE>GXPSDocument</TITLE>
+GXPSDocument
+gxps_document_get_n_pages
+gxps_document_get_page
+gxps_document_get_page_size
+gxps_document_get_page_for_anchor
+gxps_document_get_structure
+
+<SUBSECTION Standard>
+GXPS_TYPE_DOCUMENT
+GXPS_DOCUMENT
+GXPS_DOCUMENT_CLASS
+GXPS_IS_DOCUMENT
+GXPS_IS_DOCUMENT_CLASS
+GXPS_DOCUMENT_GET_CLASS
+
+<SUBSECTION Private>
+GXPSDocumentPrivate
+gxps_document_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gxps-page</FILE>
+<TITLE>GXPSPage</TITLE>
+GXPSPage
+GXPS_PAGE_ERROR
+GXPSPageError
+gxps_page_get_size
+gxps_page_render
+gxps_page_get_links
+gxps_page_get_anchor_destination
+
+<SUBSECTION Standard>
+GXPS_TYPE_PAGE
+GXPS_PAGE
+GXPS_PAGE_CLASS
+GXPS_IS_PAGE
+GXPS_IS_PAGE_CLASS
+GXPS_PAGE_GET_CLASS
+
+<SUBSECTION Private>
+GXPSPagePrivate
+gxps_page_get_type
+gxps_page_error_quark
+</SECTION>
+
+<SECTION>
+<FILE>gxps-links</FILE>
+<TITLE>GXPS Links</TITLE>
+GXPSLinkTarget
+GXPSLink
+
+<SUBSECTION>
+gxps_link_target_copy
+gxps_link_target_free
+gxps_link_target_is_internal
+gxps_link_target_get_anchor
+gxps_link_target_get_uri
+
+<SUBSECTION>
+gxps_link_copy
+gxps_link_free
+gxps_link_get_target
+gxps_link_get_area
+
+<SUBSECTION Standard>
+GXPS_TYPE_LINK_TARGET
+GXPS_TYPE_LINK
+
+<SUBSECTION Private>
+gxps_link_target_get_type
+gxps_link_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gxps-document-structure</FILE>
+<TITLE>GXPSDocumentStructure</TITLE>
+GXPSDocumentStructure
+GXPSOutlineIter
+gxps_document_structure_has_outline
+
+<SUBSECTION>
+gxps_document_structure_outline_iter_init
+gxps_outline_iter_next
+gxps_outline_iter_children
+gxps_outline_iter_get_description
+gxps_outline_iter_get_target
+
+<SUBSECTION Standard>
+GXPS_TYPE_DOCUMENT_STRUCTURE
+GXPS_DOCUMENT_STRUCTURE
+GXPS_DOCUMENT_STRUCTURE_CLASS
+GXPS_IS_DOCUMENT_STRUCTURE
+GXPS_IS_DOCUMENT_STRUCTURE_CLASS
+GXPS_DOCUMENT_STRUCTURE_GET_CLASS
+
+<SUBSECTION Private>
+GXPSDocumentStructurePrivate
+gxps_document_structure_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gxps-error</FILE>
+GXPS_ERROR
+GXPSError
+
+<SUBSECTION Private>
+gxps_error_quark
+</SECTION>
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
new file mode 100644
index 0000000..a24f987
--- /dev/null
+++ b/docs/reference/version.xml.in
@@ -0,0 +1 @@
+ PACKAGE_VERSION@
diff --git a/libgxps/gxps-document-structure.c b/libgxps/gxps-document-structure.c
index b977b31..447da37 100644
--- a/libgxps/gxps-document-structure.c
+++ b/libgxps/gxps-document-structure.c
@@ -25,6 +25,21 @@
 #include "gxps-private.h"
 #include "gxps-error.h"
 
+/**
+ * SECTION:gxps-document-structure
+ * @Short_description: Structure of XPS Document
+ * @Title: GXPSDocumentStructure
+ * @See_also: #GXPSDocument, #GXPSLinkTarget
+ *
+ * #GXPSDocumentStructure represents the structural organization of
+ * a XPS document. A #GXPSDocumentStructure can contain the document
+ * outline, similar to a table of contents, containing hyperlinks.
+ * To iterate over the outline items you can use #GXPSOutlineIter.
+ *
+ * #GXPSDocumentStructure objects can not be created directly, they
+ * are retrieved from a #GXPSDocument with gxps_document_get_structure().
+ */
+
 enum {
 	PROP_0,
 	PROP_ARCHIVE,
@@ -334,6 +349,14 @@ static const GMarkupParser check_outline_parser = {
 	NULL
 };
 
+/**
+ * gxps_document_structure_has_outline:
+ * @structure: a #GXPSDocumentStructure
+ *
+ * Whether @structure has an outline or not.
+ *
+ * Returns: %TRUE if @structure has an outline, %FALSE otherwise.
+ */
 gboolean
 gxps_document_structure_has_outline (GXPSDocumentStructure *structure)
 {
@@ -359,6 +382,41 @@ typedef struct {
 	GList                 *current;
 } OutlineIter;
 
+/**
+ * gxps_document_structure_outline_iter_init:
+ * @iter: an uninitialized #GXPSOutlineIter
+ * @structure: a #GXPSDocumentStructure
+ *
+ * Initializes @iter to the root item of the outline contained by @structure
+ * and a associates it with @structure.
+ *
+ * Here is a simple example of some code that walks the full outline:
+ *
+ * <informalexample><programlisting>
+ * static void
+ * walk_outline (GXPSOutlineIter *iter)
+ * {
+ *     do {
+ *         GXPSOutlineIter child_iter;
+ *         const gchar    *description = gxps_outline_iter_get_description (iter);
+ *         GXPSLinkTarget *target = gxps_outline_iter_get_target (iter);
+ *
+ *         /<!-- -->* Do something with description and taregt *<!-- -->/
+ *         if (gxps_outline_iter_children (&child_iter, iter))
+ *             walk_outline (&child_iter);
+ *     } while (gxps_outline_iter_next (iter));
+ * }
+ * ...
+ * {
+ *     GXPSOutlineIter iter;
+ *     if (gxps_document_structure_outline_iter_init (&iter, structure))
+ *         walk_outline (&iter);
+ * }
+ * </programlisting></informalexample>
+ *
+ * Returns: %TRUE if @iter was successfully initialized to the root item,
+ *     %FALSE if it failed or @structure does not have an outline.
+ */
 gboolean
 gxps_document_structure_outline_iter_init (GXPSOutlineIter       *iter,
 					   GXPSDocumentStructure *structure)
@@ -376,6 +434,17 @@ gxps_document_structure_outline_iter_init (GXPSOutlineIter       *iter,
 	return oi->current != NULL;
 }
 
+/**
+ * gxps_outline_iter_next:
+ * @iter: an initialized #GXPSOutlineIter
+ *
+ * Advances @iter to the next item at the current level.
+ * See gxps_document_structure_outline_iter_init() for
+ * more details.
+ *
+ * Returns: %TRUE if @iter was set to the next item,
+ *     %FALSE if the end of the current level has been reached
+ */
 gboolean
 gxps_outline_iter_next (GXPSOutlineIter *iter)
 {
@@ -388,6 +457,18 @@ gxps_outline_iter_next (GXPSOutlineIter *iter)
 	return oi->current != NULL;
 }
 
+/**
+ * gxps_outline_iter_children:
+ * @iter: an uninitialized #GXPSOutlineIter
+ * @parent: an initialized #GXPSOutlineIter
+ *
+ * Initializes @iter to the first child item of @parent.
+ * See gxps_document_structure_outline_iter_init() for
+ * more details.
+ *
+ * Returns: %TRUE if @iter was set to the first child of @parent,
+ *     %FALSE if @parent does not have children.
+ */
 gboolean
 gxps_outline_iter_children (GXPSOutlineIter *iter,
 			    GXPSOutlineIter *parent)
@@ -408,6 +489,16 @@ gxps_outline_iter_children (GXPSOutlineIter *iter,
 	return TRUE;
 }
 
+/**
+ * gxps_outline_iter_get_description:
+ * @iter: an initialized #GXPSOutlineIter
+ *
+ * Gets the description of the outline item associated with @iter.
+ * See gxps_document_structure_outline_iter_init() for
+ * more details.
+ *
+ * Returns: the description of the outline item
+ */
 const gchar *
 gxps_outline_iter_get_description (GXPSOutlineIter *iter)
 {
@@ -421,6 +512,17 @@ gxps_outline_iter_get_description (GXPSOutlineIter *iter)
 	return node->desc;
 }
 
+/**
+ * gxps_outline_iter_get_target:
+ * @iter: an initialized #GXPSOutlineIter
+ *
+ * Gets the #GXPSLinkTarget of the outline item associated with @iter.
+ * See gxps_document_structure_outline_iter_init() for
+ * more details.
+ *
+ * Returns: a new allocated #GXPSLinkTarget.
+ *     Free the returned object with gxps_link_target_free().
+ */
 GXPSLinkTarget *
 gxps_outline_iter_get_target (GXPSOutlineIter *iter)
 {
diff --git a/libgxps/gxps-document-structure.h b/libgxps/gxps-document-structure.h
index 8db1a4c..87e584b 100644
--- a/libgxps/gxps-document-structure.h
+++ b/libgxps/gxps-document-structure.h
@@ -40,9 +40,16 @@ typedef struct _GXPSDocumentStructure        GXPSDocumentStructure;
 typedef struct _GXPSDocumentStructureClass   GXPSDocumentStructureClass;
 typedef struct _GXPSDocumentStructurePrivate GXPSDocumentStructurePrivate;
 
+/**
+ * GXPSDocumentStructure:
+ *
+ * The <structname>GXPSDocumentStructure</structname> struct contains
+ * only private fields and should not be directly accessed.
+ */
 struct _GXPSDocumentStructure {
 	GObject parent;
 
+        /*< private >*/
 	GXPSDocumentStructurePrivate *priv;
 };
 
@@ -50,6 +57,13 @@ struct _GXPSDocumentStructureClass {
 	GObjectClass parent_class;
 };
 
+/**
+ * GXPSOutlineIter:
+ *
+ * GXPSOutlineIter represents an iterator that can be
+ * used to iterate over the items of an outline
+ * contained in a #GXPSDocumentStructure
+ */
 typedef struct _GXPSOutlineIter GXPSOutlineIter;
 struct _GXPSOutlineIter {
 	/*< private >*/
diff --git a/libgxps/gxps-document.c b/libgxps/gxps-document.c
index 65250f3..e4758aa 100644
--- a/libgxps/gxps-document.c
+++ b/libgxps/gxps-document.c
@@ -28,6 +28,17 @@
 #include "gxps-private.h"
 #include "gxps-error.h"
 
+/**
+ * SECTION:gxps-document
+ * @Short_description: XPS Documents
+ * @Title: GXPSDocument
+ * @See_also: #GXPSFile, #GXPSPage, #GXPSDocumentStructure
+ *
+ * #GXPSDocument represents a document in a #GXPSFile. #GXPSDocument
+ * objects can not be created directly, they are retrieved from a
+ * #GXPSFile with gxps_file_get_document().
+ */
+
 enum {
 	PROP_0,
 	PROP_ARCHIVE,
@@ -443,6 +454,14 @@ _gxps_document_new (GXPSArchive *zip,
 			       NULL);
 }
 
+/**
+ * gxps_document_get_n_pages:
+ * @doc: a #GXPSDocument
+ *
+ * Gets the number of pages in @doc.
+ *
+ * Returns: the number of pages.
+ */
 guint
 gxps_document_get_n_pages (GXPSDocument *doc)
 {
@@ -451,6 +470,18 @@ gxps_document_get_n_pages (GXPSDocument *doc)
 	return doc->priv->n_pages;
 }
 
+/**
+ * gxps_document_get_page:
+ * @doc: a #GXPSDocument
+ * @n_page: the index of the page to get
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Creates a new #GXPSPage representing the page at
+ * index @n_doc in @doc document.
+ *
+ * Returns: a new #GXPSPage or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ */
 GXPSPage *
 gxps_document_get_page (GXPSDocument *doc,
 			guint         n_page,
@@ -467,6 +498,18 @@ gxps_document_get_page (GXPSDocument *doc,
 	return _gxps_page_new (doc->priv->zip, source, error);
 }
 
+/**
+ * gxps_document_get_page_size:
+ * @doc: a #GXPSDocument
+ * @n_page: the index of a page in @doc
+ * @width: (out) (allow-none): return location for the width of @n_page
+ * @height: (out) (allow-none): return location for the height of @n_page
+ *
+ * Gets the size of the page at index @n_page in @doc document.
+ * This function is useful to get the size of the pages in a document
+ * without creating #GXPSPage objects. To get the size of a #GXPSPage
+ * you can use gxps_page_get_size() instead.
+ */
 gboolean
 gxps_document_get_page_size (GXPSDocument *doc,
 			     guint         n_page,
@@ -490,6 +533,16 @@ gxps_document_get_page_size (GXPSDocument *doc,
 	return TRUE;
 }
 
+/**
+ * gxps_document_get_page_for_anchor:
+ * @doc: a #GXPSDocument
+ * @anchor: the name of an anchor
+ *
+ * Gets the index of the page in @doc where the given
+ * anchor is.
+ *
+ * Returns: the page index of the given anchor.
+ */
 gint
 gxps_document_get_page_for_anchor (GXPSDocument *doc,
 				   const gchar  *anchor)
@@ -507,6 +560,16 @@ gxps_document_get_page_for_anchor (GXPSDocument *doc,
 	return -1;
 }
 
+/**
+ * gxps_document_get_structure:
+ * @doc: a a #GXPSDocument
+ *
+ * Creates a new #GXPSDocumentStructure representing the document
+ * structure of @doc.
+ *
+ * Returns: a new #GXPSDocumentStructure or %NULL if document doesn't have a structure.
+ *     Free the returned object with g_object_unref().
+ */
 GXPSDocumentStructure *
 gxps_document_get_structure (GXPSDocument *doc)
 {
diff --git a/libgxps/gxps-document.h b/libgxps/gxps-document.h
index f05e0c4..ae2499e 100644
--- a/libgxps/gxps-document.h
+++ b/libgxps/gxps-document.h
@@ -43,9 +43,16 @@ typedef struct _GXPSDocument        GXPSDocument;
 typedef struct _GXPSDocumentClass   GXPSDocumentClass;
 typedef struct _GXPSDocumentPrivate GXPSDocumentPrivate;
 
+/**
+ * GXPSDocument:
+ *
+ * The <structname>GXPSDocument</structname> struct contains
+ * only private fields and should not be directly accessed.
+ */
 struct _GXPSDocument {
 	GObject parent;
 
+        /*< private >*/
 	GXPSDocumentPrivate *priv;
 };
 
diff --git a/libgxps/gxps-error.c b/libgxps/gxps-error.c
index 932a3b3..7656c35 100644
--- a/libgxps/gxps-error.c
+++ b/libgxps/gxps-error.c
@@ -21,6 +21,12 @@
 
 #include "gxps-error.h"
 
+/**
+ * SECTION:gxps-error
+ * @Short_description: GXPS Errors
+ * @Title: GXPSError
+ */
+
 GQuark
 gxps_error_quark (void)
 {
diff --git a/libgxps/gxps-error.h b/libgxps/gxps-error.h
index 643eb7d..a29d5dc 100644
--- a/libgxps/gxps-error.h
+++ b/libgxps/gxps-error.h
@@ -28,8 +28,23 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GXPS_ERROR:
+ *
+ * Error domain for GXPS. Errors in this domain will be from
+ * the #GXPSError enumeration.
+ * See #GError for more information on error domains.
+ */
 #define GXPS_ERROR (gxps_error_quark ())
 
+/**
+ * GXPSError:
+ * @GXPS_ERROR_SOURCE_NOT_FOUND: Internal source file not found in XPS file
+ * @GXPS_ERROR_FONT: Error loading fonts
+ * @GXPS_ERROR_IMAGE: Error loading images
+ *
+ * Error codes returned by GXPS functions.
+ */
 typedef enum {
 	GXPS_ERROR_SOURCE_NOT_FOUND,
 	GXPS_ERROR_FONT,
diff --git a/libgxps/gxps-file.c b/libgxps/gxps-file.c
index 10002e6..47d2d92 100644
--- a/libgxps/gxps-file.c
+++ b/libgxps/gxps-file.c
@@ -26,6 +26,18 @@
 #include "gxps-private.h"
 #include "gxps-error.h"
 
+/**
+ * SECTION:gxps-file
+ * @Short_description: XPS Files
+ * @Title: GXPSFile
+ * @See_also: #GXPSDocument, #GXPSLinkTarget
+ *
+ * #GXPSFile represents a XPS file. A #GXPSFile is a set of one or more
+ * documents, you can get the amount of documents contained in the set
+ * with gxps_file_get_n_documents(). Documents can be retrieved by their
+ * index in the set with gxps_file_get_document().
+ */
+
 enum {
 	PROP_0,
 	PROP_FILE
@@ -359,6 +371,15 @@ initable_iface_init (GInitableIface *initable_iface)
 	initable_iface->init = gxps_file_initable_init;
 }
 
+/**
+ * gxps_file_new:
+ * @filename: a #GFile
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Creates a new #GXPSFile for the given #GFile.
+ *
+ * Returns: a #GXPSFile or %NULL on error.
+ */
 GXPSFile *
 gxps_file_new (GFile   *filename,
 	       GError **error)
@@ -371,6 +392,14 @@ gxps_file_new (GFile   *filename,
 			       NULL);
 }
 
+/**
+ * gxps_file_get_n_documents:
+ * @xps: a #GXPSFile
+ *
+ * Gets the number of documents in @xps.
+ *
+ * Returns: the number of documents.
+ */
 guint
 gxps_file_get_n_documents (GXPSFile *xps)
 {
@@ -379,6 +408,18 @@ gxps_file_get_n_documents (GXPSFile *xps)
 	return g_list_length (xps->priv->docs);
 }
 
+/**
+ * gxps_file_get_document:
+ * @xps: a #GXPSFile
+ * @n_doc: the index of the document to get
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Creates a new #GXPSDocument representing the document at
+ * index @n_doc in @xps file.
+ *
+ * Returns: a new #GXPSDocument or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ */
 GXPSDocument *
 gxps_file_get_document (GXPSFile *xps,
 			guint     n_doc,
@@ -394,6 +435,22 @@ gxps_file_get_document (GXPSFile *xps,
 	return _gxps_document_new (xps->priv->zip, source, error);
 }
 
+/**
+ * gxps_file_get_document_for_link_target:
+ * @xps: a #GXPSFile
+ * @target: a #GXPSLinkTarget
+ *
+ * Gets the index of the document in @xps pointed by @target.
+ * If the #GXPSLinkTarget does not reference a document, or
+ * referenced document is not found in @xps file -1 will be
+ * returned. In this case you can look for the page pointed by
+ * the link target by calling gxps_document_get_page_for_anchor()
+ * with the anchor of the #GXPSLinkTarget for every document in
+ * @xps.
+ *
+ * Returns: the index of the document pointed by the given
+ *     #GXPSLinkTarget or -1.
+ */
 gint
 gxps_file_get_document_for_link_target (GXPSFile       *xps,
 					GXPSLinkTarget *target)
diff --git a/libgxps/gxps-file.h b/libgxps/gxps-file.h
index da6ed22..252cc91 100644
--- a/libgxps/gxps-file.h
+++ b/libgxps/gxps-file.h
@@ -39,8 +39,21 @@ G_BEGIN_DECLS
 #define GXPS_IS_FILE_CLASS(obj)  (G_TYPE_CHECK_CLASS_TYPE (obj, GXPS_TYPE_FILE))
 #define GXPS_FILE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GXPS_TYPE_FILE, GXPSFileClass))
 
+/**
+ * GXPS_FILE_ERROR:
+ *
+ * Error domain for #GXPSFile. Errors in this domain will be from
+ * the #GXPSFileError enumeration.
+ * See #GError for more information on error domains.
+ */
 #define GXPS_FILE_ERROR          (gxps_file_error_quark ())
 
+/**
+ * GXPSFileError:
+ * @GXPS_FILE_ERROR_INVALID: The XPS is invalid.
+ *
+ * Error codes returned by #GXPSFile functions.
+ */
 typedef enum {
 	GXPS_FILE_ERROR_INVALID
 } GXPSFileError;
@@ -49,9 +62,16 @@ typedef struct _GXPSFile        GXPSFile;
 typedef struct _GXPSFileClass   GXPSFileClass;
 typedef struct _GXPSFilePrivate GXPSFilePrivate;
 
+/**
+ * GXPSFile:
+ *
+ * The <structname>GXPSFile</structname> struct contains
+ * only private fields and should not be directly accessed.
+ */
 struct _GXPSFile {
 	GObject parent;
 
+        /*< private >*/
 	GXPSFilePrivate *priv;
 };
 
diff --git a/libgxps/gxps-links.c b/libgxps/gxps-links.c
index aaf8ff7..1e9d48b 100644
--- a/libgxps/gxps-links.c
+++ b/libgxps/gxps-links.c
@@ -24,6 +24,27 @@
 #include "gxps-links.h"
 #include "gxps-private.h"
 
+/**
+ * SECTION:gxps-links
+ * @Short_description: XPS Links
+ * @Title: GXPS Links
+ * @See_also: #GXPSFile, #GXPSPage, #GXPSDocumentStructure
+ *
+ * #GXPSLinkTarget is a hyperlink source that can point to a location in
+ * any of the documents of the XPS file or to an external document.
+ * Internal #GXPSLinkTarget<!-- -->s have an URI relative to the XPS file,
+ * and a named destination represented by an anchor. External
+ * #GXPSLinkTarget<!-- -->s have an absolute URI pointing to a location
+ * in another XPS File and might optionally have an anchor.
+ * To get the destination pointed by a in internal #GXPSLinkTarget you can use
+ * gxps_file_get_document_for_link_target() to get the document within the file,
+ * gxps_document_get_page_for_anchor() to get the page within the document, and
+ * gxps_page_get_anchor_destination() to get the page area.
+ *
+ * #GXPSLink maps a location in a page to a #GXPSLinkTarget. To get the list of
+ * link for a page you can use gxps_page_get_links().
+ */
+
 struct _GXPSLink {
 	GXPSLinkTarget   *target;
 	cairo_rectangle_t area;
@@ -38,6 +59,15 @@ struct _GXPSLinkTarget {
 G_DEFINE_BOXED_TYPE (GXPSLink, gxps_link, gxps_link_copy, gxps_link_free)
 G_DEFINE_BOXED_TYPE (GXPSLinkTarget, gxps_link_target, gxps_link_target_copy, gxps_link_target_free)
 
+/**
+ * gxps_link_copy:
+ * @link: a #GXPSLink
+ *
+ * Creates a copy of a #GXPSLink.
+ *
+ * Returns: a copy of @link.
+ *     Free the returned object with gxps_link_free().
+ */
 GXPSLink *
 gxps_link_copy (GXPSLink *link)
 {
@@ -52,6 +82,12 @@ gxps_link_copy (GXPSLink *link)
 	return link_copy;
 }
 
+/**
+ * gxps_link_free:
+ * @link: a #GXPSLink
+ *
+ * Frees a #GXPSLink.
+ */
 void
 gxps_link_free (GXPSLink *link)
 {
@@ -62,12 +98,28 @@ gxps_link_free (GXPSLink *link)
 	g_slice_free (GXPSLink, link);
 }
 
+/**
+ * gxps_link_get_target:
+ * @link: a #GXPSLink
+ *
+ * Gets the #GXPSLinkTarget mapped by @link.
+ *
+ * Returns: (transfer none): the #GXPSLinkTarget of @link.
+ */
 GXPSLinkTarget *
 gxps_link_get_target (GXPSLink *link)
 {
 	return link->target;
 }
 
+/**
+ * gxps_link_get_area:
+ * @link: a #GXPSLink
+ * @area: (out): return location for page area
+ *
+ * Gets the rectangle of a page where the #GXPSLinkTarget
+ * mapped by @link is.
+ */
 void
 gxps_link_get_area (GXPSLink          *link,
 		    cairo_rectangle_t *area)
@@ -75,6 +127,15 @@ gxps_link_get_area (GXPSLink          *link,
 	*area = link->area;
 }
 
+/**
+ * gxps_link_target_copy:
+ * @target: a #GXPSLinkTarget
+ *
+ * Creates a copy of a #GXPSLinkTarget
+ *
+ * Returns: a copy of @target.
+ *     Free the returned object with gxps_link_target_free()
+ */
 GXPSLinkTarget *
 gxps_link_target_copy (GXPSLinkTarget *target)
 {
@@ -89,6 +150,12 @@ gxps_link_target_copy (GXPSLinkTarget *target)
 	return target_copy;
 }
 
+/**
+ * gxps_link_target_free:
+ * @target: a #GXPSLinkTarget
+ *
+ * Frees a #GXPSLinkTarget.
+ */
 void
 gxps_link_target_free (GXPSLinkTarget *target)
 {
@@ -100,18 +167,46 @@ gxps_link_target_free (GXPSLinkTarget *target)
 	g_slice_free (GXPSLinkTarget, target);
 }
 
+/**
+ * gxps_link_target_is_internal:
+ * @target: a #GXPSLinkTarget
+ *
+ * Gets whether @target destination is internal or not.
+ *
+ * Returns: %TRUE if the #GXPSLinkTarget points to an internal location,
+ *     %FALSE if it points to a external one.
+ */
 gboolean
 gxps_link_target_is_internal (GXPSLinkTarget *target)
 {
 	return target->is_internal;
 }
 
+/**
+ * gxps_link_target_get_anchor:
+ * @target: a #GXPSLinkTarget
+ *
+ * Gets the anchor name @target links to. If @target is
+ * an internal #GXPSLinkTarget this function always returns
+ * and anchor, if it is external it might return %NULL if the
+ * @target does not have an anchor.
+ *
+ * Returns: the name of the anchor of @target.
+ */
 const gchar *
 gxps_link_target_get_anchor (GXPSLinkTarget *target)
 {
 	return target->anchor;
 }
 
+/**
+ * gxps_link_target_get_uri:
+ * @target: a #GXPSLinkTarget
+ *
+ * Gets the URI @target links to.
+ *
+ * Returns: the URI of @target.
+ */
 const gchar *
 gxps_link_target_get_uri (GXPSLinkTarget *target)
 {
diff --git a/libgxps/gxps-links.h b/libgxps/gxps-links.h
index aaa0b8c..22bf6b4 100644
--- a/libgxps/gxps-links.h
+++ b/libgxps/gxps-links.h
@@ -32,7 +32,18 @@ G_BEGIN_DECLS
 #define GXPS_TYPE_LINK        (gxps_link_get_type ())
 #define GXPS_TYPE_LINK_TARGET (gxps_link_target_get_type ())
 
+/**
+ * GXPSLink:
+ *
+ * GXPSLink maps a location in a page to a #GXPSLinkTarget.
+ */
 typedef struct _GXPSLink       GXPSLink;
+
+/**
+ * GXPSLinkTarget:
+ *
+ * GXPSLinkTarget represents a hyperlink source.
+ */
 typedef struct _GXPSLinkTarget GXPSLinkTarget;
 
 GType           gxps_link_get_type            (void) G_GNUC_CONST;
diff --git a/libgxps/gxps-page.c b/libgxps/gxps-page.c
index 5fe5dd2..4efa196 100644
--- a/libgxps/gxps-page.c
+++ b/libgxps/gxps-page.c
@@ -30,6 +30,18 @@
 #include "gxps-private.h"
 #include "gxps-error.h"
 
+/**
+ * SECTION:gxps-page
+ * @Short_description: Page of XPS document
+ * @Title: GXPSPage
+ * @See_also: #GXPSDocument, #GXPSLink, #GXPSLinkTarget
+ *
+ * #GXPSPage represents a page in a XPS document. #GXPSPage<!-- -->s
+ * can be rendered into a cairo context with gxps_page_render().
+ * #GXPSPage objects can not be created directly, they are retrieved
+ * from a #GXPSDocument with gxps_document_get_page().
+ */
+
 // #define ENABLE_LOG
 
 #ifdef ENABLE_LOG
@@ -3400,6 +3412,14 @@ _gxps_page_new (GXPSArchive *zip,
 			       NULL);
 }
 
+/**
+ * gxps_page_get_size:
+ * @page: a #GXPSPage
+ * @width: (out) (allow-none): return location for the page width
+ * @height: (out) (allow-none): return location for the page height
+ *
+ * Gets the size of the page.
+ */
 void
 gxps_page_get_size (GXPSPage *page,
 		    guint    *width,
@@ -3413,6 +3433,19 @@ gxps_page_get_size (GXPSPage *page,
 		*height = page->priv->height;
 }
 
+/**
+ * gxps_page_render:
+ * @page: a #GXPSPage
+ * @cr: a cairo context to render to
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Render the page to the given cairo context. In case of
+ * error, %FALSE is returned and @error is filled with
+ * information about error.
+ *
+ * Returns: %TRUE if page was successfully rendered,
+ *     %FALSE otherwise.
+ */
 gboolean
 gxps_page_render (GXPSPage *page,
 		  cairo_t  *cr,
@@ -3424,6 +3457,19 @@ gxps_page_render (GXPSPage *page,
 	return gxps_page_parse_for_rendering (page, cr, error);
 }
 
+/**
+ * gxps_page_get_links:
+ * @page: a #GXPSPage
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Gets a list of #GXPSLink items that map from a location
+ * in @page to a #GXPSLinkTarget. Items in the list should
+ * be freed with gxps_link_free() and the list itself with
+ * g_list_free() when done.
+ *
+ * Returns: (element-type GXPS.Link) (transfer full):  a #GList
+ *     of #GXPSLink items.
+ */
 GList *
 gxps_page_get_links (GXPSPage *page,
 		     GError  **error)
@@ -3447,6 +3493,20 @@ gxps_page_get_links (GXPSPage *page,
 	return links;
 }
 
+/**
+ * gxps_page_get_anchor_destination:
+ * @page: a #GXPSPage
+ * @anchor: the name of an anchor in @page
+ * @area: (out): return location for page area of @anchor
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Gets the rectangle of @page corresponding to the destination
+ * of the given anchor. If @anchor is not found in @page, %FALSE
+ * will be returned and @error will contain %GXPS_PAGE_ERROR_INVALID_ANCHOR
+ *
+ * Returns: %TRUE if the destination for the anchor was found in page
+ *     and @area contains the rectangle, %FALSE otherwise.
+ */
 gboolean
 gxps_page_get_anchor_destination (GXPSPage          *page,
 				  const gchar       *anchor,
diff --git a/libgxps/gxps-page.h b/libgxps/gxps-page.h
index 38fb22c..efaf7de 100644
--- a/libgxps/gxps-page.h
+++ b/libgxps/gxps-page.h
@@ -37,8 +37,23 @@ G_BEGIN_DECLS
 #define GXPS_IS_PAGE_CLASS(obj)  (G_TYPE_CHECK_CLASS_TYPE (obj, GXPS_TYPE_PAGE))
 #define GXPS_PAGE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GXPS_TYPE_PAGE, GXPSPageClass))
 
+/**
+ * GXPS_PAGE_ERROR:
+ *
+ * Error domain for #GXPSPage. Errors in this domain will be from
+ * #GXPSPageError enumeration.
+ * See #GError for more information on error domains.
+ */
 #define GXPS_PAGE_ERROR          (gxps_page_error_quark ())
 
+/**
+ * GXPSPageError:
+ * @GXPS_PAGE_ERROR_INVALID: The page is invalid.
+ * @GXPS_PAGE_ERROR_RENDER: Error rendering the page.
+ * @GXPS_PAGE_ERROR_INVALID_ANCHOR: Anchor is invalid for the page.
+ *
+ * Error codes returned by #GXPSPage functions
+ */
 typedef enum {
 	GXPS_PAGE_ERROR_INVALID,
 	GXPS_PAGE_ERROR_RENDER,
@@ -49,9 +64,16 @@ typedef struct _GXPSPage        GXPSPage;
 typedef struct _GXPSPageClass   GXPSPageClass;
 typedef struct _GXPSPagePrivate GXPSPagePrivate;
 
+/**
+ * GXPSPage:
+ *
+ * The <structname>GXPSPage</structname> struct contains
+ * only private fields and should not be directly accessed.
+ */
 struct _GXPSPage {
 	GObject parent;
 
+        /*< private >*/
 	GXPSPagePrivate *priv;
 };
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]