GNOME.org
 

[gcab] Start gtk-doc reference manual

commit d01abc558785d11b97a9b9fad6ea720163d46605
Author: Marc-Andrà Lureau <marcandre lureau gmail com>
Date:   Fri Jan 18 03:28:38 2013 +0100

    Start gtk-doc reference manual

 Makefile.am                      |    4 ++-
 autogen.sh                       |    3 +-
 configure.ac                     |    6 +++-
 docs/Makefile.am                 |    1 +
 docs/reference/Makefile.am       |   40 ++++++++++++++++++++++
 docs/reference/gcab-docs.sgml    |   40 ++++++++++++++++++++++
 docs/reference/gcab-sections.txt |   67 ++++++++++++++++++++++++++++++++++++++
 libgcab/gcab-cabinet.c           |   23 ++++++++++++-
 libgcab/gcab-cabinet.h           |   13 +++++++
 libgcab/gcab-file.c              |   43 ++++++++++++++++++++++++
 libgcab/gcab-folder.c            |   20 +++++++++++
 libgcab/gcab-folder.h            |    7 ++++
 12 files changed, 262 insertions(+), 5 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 5dccd28..325d2bc 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -5,7 +5,7 @@ DISTCLEANFILES =
 ACLOCAL_AMFLAGS = -I m4
 AM_MAKEFLAGS = --no-print-directory
 
-SUBDIRS = po libgcab
+SUBDIRS = docs po libgcab
 
 AM_CPPFLAGS =					\
         -I$(top_srcdir)				\
@@ -161,6 +161,8 @@ $(TESTSUITE): tests/testsuite.at tests/package.m4
 	$(AUTOM4TE) --language=autotest -I$(builddir)/tests -o $  tmp $  at
 	mv $  tmp $@
 
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc
+
 MAINTAINERCLEANFILES =						\
 	$(srcdir)/ABOUT-NLS					\
 	$(srcdir)/INSTALL					\
diff --git a/autogen.sh b/autogen.sh
index ef1012c..6c864bc 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -6,9 +6,10 @@ srcdir=`dirname $0`
 test -z "$srcdir" && srcdir=.
 mkdir -p "$srcdir/m4"
 
+gtkdocize
 autoreconf -v --force --install
 intltoolize -f
 
 if [ -z "$NOCONFIGURE" ]; then
-    "$srcdir"/configure "$@"
+    "$srcdir"/configure --enable-gtk-doc "$@"
 fi
diff --git a/configure.ac b/configure.ac
index 5d40fdd..5807c1a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -13,6 +13,7 @@ AC_PROG_CC
 AM_PROG_CC_C_O
 AC_PROG_INSTALL
 LT_INIT([win32-dll disable-fast-install])
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
 PKG_PROG_PKG_CONFIG
 GOBJECT_INTROSPECTION_CHECK([0.9.4])
 AM_CONDITIONAL([GIR], [test "x$INTROSPECTION_MAKEFILE" != x])
@@ -48,10 +49,13 @@ AC_CHECK_HEADERS([zlib.h], [], [AC_MSG_ERROR([zlib required])])
 
 AC_OUTPUT([
   Makefile
+  docs/Makefile
+  docs/reference/Makefile
+  docs/reference/gcab-docs.sgml
   gcab.1
   libgcab-1.0.pc
-  po/Makefile.in
   libgcab/Makefile
+  po/Makefile.in
 ])
 
 AC_MSG_NOTICE([
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..f3ddc22
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = reference
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..548e7f0
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,40 @@
+NULL =
+AUTOMAKE_OPTIONS = 1.6
+
+DOC_MODULE = gcab
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml
+DOC_SOURCE_DIR = $(top_srcdir)/libgcab
+
+SCANGOBJ_OPTIONS =
+SCAN_OPTIONS = --rebuild-types
+MKDB_OPTIONS = --xml-mode --output-format=xml
+MKTMPL_OPTIONS =
+MKHTML_OPTIONS =
+FIXXREF_OPTIONS =
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB = $(top_srcdir)/libgcab/*.h
+CFILE_GLOB = $(top_srcdir)/libgcab/*.c
+EXTRA_HFILES =
+IGNORE_HFILES =					\
+	cabinet.h				\
+	gcab-priv.h				\
+	glib-compat.h				\
+	$(NULL)
+
+GTKDOC_CFLAGS =
+GTKDOC_LIBS = $(top_builddir)/libgcab-1.0.la
+
+include $(top_srcdir)/gtk-doc.make
+
+EXTRA_DIST += gcab-docs.sgml.in
+DISTCLEANFILES = $(DOC_MODULE).types
+
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = cd $(srcdir) &&					\
+  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE)	\
+  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
+
+-include $(top_srcdir)/git.mk
diff --git a/docs/reference/gcab-docs.sgml b/docs/reference/gcab-docs.sgml
new file mode 100644
index 0000000..bc6c208
--- /dev/null
+++ b/docs/reference/gcab-docs.sgml
@@ -0,0 +1,40 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>GCab Reference Manual</title>
+    <releaseinfo>
+      This document is generated from the version gcab 0.1.13-ba9f-dirty.
+      <!-- <ulink role="online-location"
+                  url="http://fixme/gcab/index.html";>
+             http://fixme/gcab/
+           </ulink>. -->
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>Cabinet API</title>
+    <xi:include href="xml/gcab-cabinet.xml"/>
+    <xi:include href="xml/gcab-folder.xml"/>
+    <xi:include href="xml/gcab-file.xml"/>
+  </chapter>
+
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
diff --git a/docs/reference/gcab-sections.txt b/docs/reference/gcab-sections.txt
new file mode 100644
index 0000000..d68cbea
--- /dev/null
+++ b/docs/reference/gcab-sections.txt
@@ -0,0 +1,67 @@
+<SECTION>
+<FILE>gcab-cabinet</FILE>
+GCabCabinet
+gcab_cabinet_new
+gcab_cabinet_load
+gcab_cabinet_extract
+gcab_cabinet_extract_simple
+gcab_cabinet_get_folders
+gcab_cabinet_add_folder
+gcab_cabinet_write
+gcab_cabinet_write_simple
+GCAB_ERROR
+GCabError
+gcab_error_quark
+<SUBSECTION Standard>
+GCAB_CABINET
+GCAB_CABINET_CLASS
+GCAB_CABINET_GET_CLASS
+GCAB_IS_CABINET
+GCAB_IS_CABINET_CLASS
+GCAB_TYPE_CABINET
+gcab_cabinet_get_type
+<SUBSECTION Private>
+GCabCabinetClass
+</SECTION>
+
+<SECTION>
+<FILE>gcab-file</FILE>
+GCabFileCallback
+GCabFile
+gcab_file_new_with_file
+gcab_file_get_file
+gcab_file_get_name
+gcab_file_get_extract_name
+gcab_file_set_extract_name
+<SUBSECTION Standard>
+GCAB_FILE
+GCAB_FILE_CLASS
+GCAB_FILE_GET_CLASS
+GCAB_IS_FILE
+GCAB_IS_FILE_CLASS
+GCAB_TYPE_FILE
+gcab_file_get_type
+GCabFileClass
+</SECTION>
+
+<SECTION>
+<FILE>gcab-folder</FILE>
+GCabCompression
+GCabFolder
+gcab_folder_new
+gcab_folder_add_file
+gcab_folder_get_files
+gcab_folder_get_nfiles
+<SUBSECTION Standard>
+GCAB_FOLDER
+GCAB_FOLDER_CLASS
+GCAB_FOLDER_GET_CLASS
+GCAB_IS_FOLDER
+GCAB_IS_FOLDER_CLASS
+GCAB_TYPE_FOLDER
+gcab_folder_get_type
+GCAB_TYPE_COMPRESSION
+gcab_compression_get_type
+GCabFolderClass
+</SECTION>
+
diff --git a/libgcab/gcab-cabinet.c b/libgcab/gcab-cabinet.c
index ef9b4d0..0a6e981 100644
--- a/libgcab/gcab-cabinet.c
+++ b/libgcab/gcab-cabinet.c
@@ -1,5 +1,17 @@
 #include "gcab-priv.h"
 
+/**
+ * SECTION:gcab-cabinet
+ * @title: GCabCabinet
+ * @short_description: Cabinet archive file operations
+ * @see_also: #GCabFolder
+ * @stability: Stable
+ * @include: libgcab.h
+ *
+ * A GCabCabinet is a handle to a Cabinet archive. It allows examining,
+ * extracting and creation of archives.
+ */
+
 struct _GCabCabinetClass
 {
     GObjectClass parent_class;
@@ -98,8 +110,8 @@ gcab_cabinet_class_init (GCabCabinetClass *klass)
 /**
  * gcab_cabinet_add_folder:
  * @cabinet: a #GCabCabinet
- * @folder:
- * @error:
+ * @folder: a #GCabFolder
+ * @error: (allow-none): #GError to set on error, or %NULL
  *
  * Add @folder to @cabinet.
  *
@@ -123,6 +135,10 @@ gcab_cabinet_add_folder (GCabCabinet *self,
  * gcab_cabinet_get_folders:
  * @cabinet:a #GCabCabinet
  *
+ * Get the Cabinet folders within the @cabinet.
+ * Note that Cabinet folders are not like filesystem path, they are
+ * group of files sharing some layout parameters.
+ *
  * Returns: (element-type GCabFolder) (transfer full): an array of #GCabFolder
  **/
 GPtrArray *
@@ -293,6 +309,9 @@ gcab_cabinet_write_simple (GCabCabinet *self,
 /**
  * gcab_cabinet_new:
  *
+ * Create a new #GCabCabinet object to read or create a Cabinet
+ * archive.
+ *
  * Returns: a new #GCabCabinet
  **/
 GCabCabinet *
diff --git a/libgcab/gcab-cabinet.h b/libgcab/gcab-cabinet.h
index 8fdf5d5..af41043 100644
--- a/libgcab/gcab-cabinet.h
+++ b/libgcab/gcab-cabinet.h
@@ -35,9 +35,22 @@ G_BEGIN_DECLS
 #define GCAB_IS_CABINET_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GCAB_TYPE_CABINET))
 #define GCAB_CABINET_GET_CLASS(cabinet)  (G_TYPE_INSTANCE_GET_CLASS ((cabinet), GCAB_TYPE_CABINET, GCabCabinetClass))
 
+/**
+ * GCAB_ERROR:
+ *
+ * Error domain for the GCab library. See #GError for more information
+ * on error domains.
+ */
 #define GCAB_ERROR gcab_error_quark ()
 GQuark gcab_error_quark (void);
 
+/**
+ * GCabError:
+ * @GCAB_ERROR_FORMAT: The given file is not of Cabinet format.
+ * @GCAB_ERROR_FAILED: General function failure.
+ *
+ * The various errors triggered by the GCab functions.
+ **/
 typedef enum GCabError
 {
     GCAB_ERROR_FORMAT,
diff --git a/libgcab/gcab-file.c b/libgcab/gcab-file.c
index fba7836..e998537 100644
--- a/libgcab/gcab-file.c
+++ b/libgcab/gcab-file.c
@@ -1,6 +1,21 @@
 #include "gcab-priv.h"
 #include "gcab-file.h"
 
+/**
+ * SECTION:gcab-file
+ * @title: GCabFile
+ * @short_description: A file contained in the Cabinet
+ * @see_also: #GCabFolder
+ * @stability: Stable
+ * @include: libgcab.h
+ *
+ * A GCabFile is a handle to a file inside a Cabinet archive.
+ * It can either be a file that is already within an exisiting
+ * archive, or a file that reference a file on disk that will be used
+ * for a new archive creation. In the later case, gcab_file_get_file()
+ * must return a valid handle.
+ */
+
 struct _GCabFileClass
 {
     GObjectClass parent_class;
@@ -147,6 +162,8 @@ gcab_file_set_uoffset (GCabFile *self, u4 uoffset)
  * gcab_file_get_name:
  * @file: a #GCabFile
  *
+ * Get the file name within the cabinet.
+ *
  * Returns: the cabinet file name
  **/
 const gchar *
@@ -161,6 +178,13 @@ gcab_file_get_name (GCabFile *self)
  * gcab_file_get_file:
  * @file: a #GCabFile
  *
+ * If the cabinet is being created, get the #GFile associated with
+ * @file. This must be an exisiting file that can be read, in order to
+ * be added to the archive during cabinet creation.
+ *
+ * If @file is from an existing cabinet, the fuction will return
+ * %NULL.
+ *
  * Returns: (transfer full): the associated #GFile or %NULL
  **/
 GFile *
@@ -176,6 +200,9 @@ gcab_file_get_file (GCabFile *self)
  * @name: name of the file within the cabinet
  * @file: a #GFile to be added to the cabinet
  *
+ * Create a #GCabFile from a given #GFile, to be added to a
+ * #GCabCabinet for archive creation.
+ *
  * Returns: a new #GCabFile
  **/
 GCabFile *
@@ -203,6 +230,14 @@ gcab_file_new_with_cfile (const cfile_t *cfile)
     return file;
 }
 
+/**
+ * gcab_file_get_extract_name:
+ * @file: a #GCabFile
+ *
+ * Get the file name to use for extraction, or %NULL.
+ *
+ * Returns: (allow-none): a file name
+ **/
 const gchar *
 gcab_file_get_extract_name (GCabFile *self)
 {
@@ -211,6 +246,14 @@ gcab_file_get_extract_name (GCabFile *self)
     return self->extract_name ? self->extract_name : self->name;
 }
 
+/**
+ * gcab_file_set_extract_name:
+ * @file: a #GCabFile
+ * @name: (allow-none): a file name or %NULL
+ *
+ * Sets the file name to use for extraction, instead of the name
+ * provided by the Cabinet.
+ **/
 void
 gcab_file_set_extract_name (GCabFile *self, const gchar *name)
 {
diff --git a/libgcab/gcab-folder.c b/libgcab/gcab-folder.c
index 4113d50..6346e7a 100644
--- a/libgcab/gcab-folder.c
+++ b/libgcab/gcab-folder.c
@@ -1,5 +1,25 @@
 #include "gcab-priv.h"
 
+/**
+ * SECTION:gcab-folder
+ * @title: GCabFolder
+ * @short_description: A Cabinet folder
+ * @see_also: #GCabFolder
+ * @stability: Stable
+ * @include: libgcab.h
+ *
+ * A GCabFolder is a handle to a folder within the Cabinet archive. A
+ * Cabinet folder <emphasis>is not</emphasis> like a directory. It is
+ * a sub-container grouping GCabFiles together, sharing some common
+ * settings like the compression method.
+ *
+ * You can retrieve the files withing a folder with
+ * gcab_folder_get_files().
+ *
+ * In order to add a file to a folder for creation, use
+ * gcab_folder_add_file().
+ */
+
 struct _GCabFolderClass
 {
     GObjectClass parent_class;
diff --git a/libgcab/gcab-folder.h b/libgcab/gcab-folder.h
index 9df90c7..fa2b6e7 100644
--- a/libgcab/gcab-folder.h
+++ b/libgcab/gcab-folder.h
@@ -36,6 +36,13 @@ G_BEGIN_DECLS
 typedef struct _GCabFolderClass GCabFolderClass;
 typedef struct _GCabFolder GCabFolder;
 
+/**
+ * GCabCompression:
+ * @GCAB_COMPRESSION_NONE: No compression.
+ * @GCAB_COMPRESSION_MSZIP: MSZIP compression.
+ *
+ * Compression used by the #GCabFolder.
+ **/
 typedef enum
 {
     GCAB_COMPRESSION_NONE = 0,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]