[gcab] docs: pass gtk-doc make check

[Marc-Andre Lureau <malureau src gnome org>]

commit 72138987f22651ce59fb1ac8fb8761cba6a01f33
Author: Marc-Andrà Lureau <marcandre lureau gmail com>
Date:   Sun Jan 20 00:25:45 2013 +0100

    docs: pass gtk-doc make check

 docs/reference/gcab-docs.sgml.in |    1 +
 docs/reference/gcab-sections.txt |    4 +++-
 libgcab/gcab-cabinet.h           |    6 ++++++
 libgcab/gcab-file.h              |   16 +++++++++++++++-
 libgcab/gcab-folder.c            |   13 +++++++++++--
 libgcab/gcab-folder.h            |    6 ++++++
 6 files changed, 42 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/gcab-docs.sgml.in b/docs/reference/gcab-docs.sgml.in
index 2d92600..dd0a5e2 100644
--- a/docs/reference/gcab-docs.sgml.in
+++ b/docs/reference/gcab-docs.sgml.in
@@ -37,4 +37,5 @@
   </index>
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+  <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/gcab-sections.txt b/docs/reference/gcab-sections.txt
index d68cbea..aa91791 100644
--- a/docs/reference/gcab-sections.txt
+++ b/docs/reference/gcab-sections.txt
@@ -11,7 +11,6 @@ gcab_cabinet_write
 gcab_cabinet_write_simple
 GCAB_ERROR
 GCabError
-gcab_error_quark
 <SUBSECTION Standard>
 GCAB_CABINET
 GCAB_CABINET_CLASS
@@ -22,6 +21,7 @@ GCAB_TYPE_CABINET
 gcab_cabinet_get_type
 <SUBSECTION Private>
 GCabCabinetClass
+gcab_error_quark
 </SECTION>
 
 <SECTION>
@@ -41,6 +41,7 @@ GCAB_IS_FILE
 GCAB_IS_FILE_CLASS
 GCAB_TYPE_FILE
 gcab_file_get_type
+<SUBSECTION Private>
 GCabFileClass
 </SECTION>
 
@@ -62,6 +63,7 @@ GCAB_TYPE_FOLDER
 gcab_folder_get_type
 GCAB_TYPE_COMPRESSION
 gcab_compression_get_type
+<SUBSECTION Private>
 GCabFolderClass
 </SECTION>
 
diff --git a/libgcab/gcab-cabinet.h b/libgcab/gcab-cabinet.h
index af41043..9922b2d 100644
--- a/libgcab/gcab-cabinet.h
+++ b/libgcab/gcab-cabinet.h
@@ -58,6 +58,12 @@ typedef enum GCabError
 } GCabError;
 
 typedef struct _GCabCabinetClass GCabCabinetClass;
+
+/**
+ * GCabCabinet:
+ *
+ * An opaque object holding a Cabinet file reference.
+ **/
 typedef struct _GCabCabinet GCabCabinet;
 
 GType gcab_cabinet_get_type (void) G_GNUC_CONST;
diff --git a/libgcab/gcab-file.h b/libgcab/gcab-file.h
index e421de2..d26ac51 100644
--- a/libgcab/gcab-file.h
+++ b/libgcab/gcab-file.h
@@ -33,9 +33,23 @@ G_BEGIN_DECLS
 #define GCAB_FILE_GET_CLASS(file)  (G_TYPE_INSTANCE_GET_CLASS ((file), GCAB_TYPE_FILE, GCabFileClass))
 
 typedef struct _GCabFileClass GCabFileClass;
+
+/**
+ * GCabFile:
+ *
+ * An opaque object, referencing a file in a Cabinet.
+ **/
 typedef struct _GCabFile GCabFile;
 
-typedef gboolean (*GCabFileCallback) (GCabFile *current, gpointer user_data);
+/**
+ * GCabFileCallback:
+ * @file: the file being processed
+ * @user_data: user data passed to the callback.
+ *
+ * The type used for callback called when processing Cabinet archive
+ * files.
+ **/
+typedef gboolean (*GCabFileCallback) (GCabFile *file, gpointer user_data);
 
 GType gcab_file_get_type (void) G_GNUC_CONST;
 
diff --git a/libgcab/gcab-folder.c b/libgcab/gcab-folder.c
index 6346e7a..792b479 100644
--- a/libgcab/gcab-folder.c
+++ b/libgcab/gcab-folder.c
@@ -244,7 +244,9 @@ gcab_folder_add_file (GCabFolder *self, GCabFile *file,
  * gcab_folder_get_nfiles:
  * @cabfolder: a #GCabFolder
  *
- * Returns: Number of files in this @folder.
+ * Get the number of files in this @folder.
+ *
+ * Returns: a #guint
  **/
 guint
 gcab_folder_get_nfiles (GCabFolder *self)
@@ -256,7 +258,12 @@ gcab_folder_get_nfiles (GCabFolder *self)
 
 /**
  * gcab_folder_new:
- * @compression: compression used by the folder
+ * @compression: compression to used in this folder
+ *
+ * Creates a new empty Cabinet folder. Use gcab_folder_add_file() to
+ * add files to an archive.
+ *
+ * A Cabinet folder is not a file path, it is a container for files.
  *
  * Returns: a new #GCabFolder
  **/
@@ -284,6 +291,8 @@ gcab_folder_new_with_cfolder (const cfolder_t *folder, GInputStream *stream)
  * gcab_folder_get_files:
  * @cabfolder: a #GCabFolder
  *
+ * Get the list of #GCabFile files contained in the @cabfolder.
+ *
  * Returns: (element-type GCabFile) (transfer full): list of files
  **/
 GSList *
diff --git a/libgcab/gcab-folder.h b/libgcab/gcab-folder.h
index fa2b6e7..420111c 100644
--- a/libgcab/gcab-folder.h
+++ b/libgcab/gcab-folder.h
@@ -34,6 +34,12 @@ G_BEGIN_DECLS
 #define GCAB_FOLDER_GET_CLASS(folder) (G_TYPE_INSTANCE_GET_CLASS ((folder), GCAB_TYPE_FOLDER, GCabFolderClass))
 
 typedef struct _GCabFolderClass GCabFolderClass;
+
+/**
+ * GCabFolder:
+ *
+ * An opaque object, referencing a folder in a Cabinet.
+ **/
 typedef struct _GCabFolder GCabFolder;
 
 /**