Update reference manual for autoar-format-filter

2 files changed, 258 insertions, 2 deletions

diff --git a/gnome-autoar/autoar-format-filter.c b/gnome-autoar/autoar-format-filter.c
index 90d0ea6..f2e1fd9 100644
--- a/gnome-autoar/autoar-format-filter.c
+++ b/gnome-autoar/autoar-format-filter.c
@@ -31,6 +31,16 @@
 #include <gio/gio.h>
 #include <glib.h>
 
+/**
+ * SECTION:autoar-format-filter
+ * @Short_description: Utilities for handling archive formats and filters
+ * @Title: autoar-format-filter
+ * @Include: gnome-autoar/autoar.h
+ *
+ * autoar-format-filter is a collection of functions providing information
+ * of archive formats and filters.
+ **/
+
 typedef struct _AutoarFormatDescription AutoarFormatDescription;
 typedef struct _AutoarFilterDescription AutoarFilterDescription;
 
@@ -172,18 +182,41 @@ static AutoarFilterDescription autoar_filter_description[] = {
     archive_write_add_filter_lrzip }
 };
 
+/**
+ * autoar_format_last:
+ *
+ * Gets the maximal allowed values of #AutoarFormat
+ *
+ * Returns: maximal allowed values of #AutoarFormat
+ **/
 AutoarFormat
 autoar_format_last (void)
 {
   return AUTOAR_FORMAT_LAST;
 }
 
+/**
+ * autoar_format_is_valid:
+ * @format: an #AutoarFormat
+ *
+ * Checks whether an #AutoarFormat is valid.
+ *
+ * Returns: %TRUE if the value of @format is valid
+ **/
 gboolean
 autoar_format_is_valid (AutoarFormat format)
 {
   return (format > 0 && format < AUTOAR_FORMAT_LAST);
 }
 
+/**
+ * autoar_format_get_mime_type:
+ * @format: an #AutoarFormat
+ *
+ * Gets the MIME type of the format from the internal static data.
+ *
+ * Returns: (transfer none): an MIME type
+ **/
 const char*
 autoar_format_get_mime_type (AutoarFormat format)
 {
@@ -191,6 +224,14 @@ autoar_format_get_mime_type (AutoarFormat format)
   return autoar_format_description[format - 1].mime_type;
 }
 
+/**
+ * autoar_format_get_extension:
+ * @format: an #AutoarFormat
+ *
+ * Gets the file name extension of the format from the internal static data.
+ *
+ * Returns: (transfer none): a file name extension
+ **/
 const char*
 autoar_format_get_extension (AutoarFormat format)
 {
@@ -198,6 +239,14 @@ autoar_format_get_extension (AutoarFormat format)
   return autoar_format_description[format - 1].extension;
 }
 
+/**
+ * autoar_format_get_description:
+ * @format: an #AutoarFormat
+ *
+ * Gets description of the format from the internal static data.
+ *
+ * Returns: (transfer none): description about the format
+ **/
 const char*
 autoar_format_get_description (AutoarFormat format)
 {
@@ -205,6 +254,20 @@ autoar_format_get_description (AutoarFormat format)
   return autoar_format_description[format - 1].description;
 }
 
+/**
+ * autoar_format_get_format_libarchive:
+ * @format: an #AutoarFormat
+ *
+ * Gets the format code used by libarchive. You can use the return value
+ * as the argument for archive_read_support_format_by_code() and
+ * archive_write_set_format(). However, some format cannot be set using
+ * these two functions because of problems inside libarchive. Use
+ * autoar_format_get_libarchive_read() and
+ * autoar_format_get_libarchive_write() to get the function pointer
+ * is the more reliable way to set format on the archive object.
+ *
+ * Returns: an integer
+ **/
 int
 autoar_format_get_format_libarchive (AutoarFormat format)
 {
@@ -212,6 +275,16 @@ autoar_format_get_format_libarchive (AutoarFormat format)
   return autoar_format_description[format - 1].libarchive_format;
 }
 
+/**
+ * autoar_format_get_description_libarchive:
+ * @format: an #AutoarFormat
+ *
+ * Gets description of the format from libarchive. This function creates
+ * and destroys an archive object in order to get the description string.
+ *
+ * Returns: (transfer full): description about the format. Free the returned
+ * string with g_free().
+ **/
 gchar*
 autoar_format_get_description_libarchive (AutoarFormat format)
 {
@@ -228,6 +301,15 @@ autoar_format_get_description_libarchive (AutoarFormat format)
   return str;
 }
 
+/**
+ * autoar_format_get_libarchive_read:
+ * @format: an #AutoarFormat
+ *
+ * Gets the function used to set format on the object returned by
+ * archive_read_new().
+ *
+ * Returns: function pointer to the setter function provided by libarchive
+ **/
 AutoarFormatFunc
 autoar_format_get_libarchive_read (AutoarFormat format)
 {
@@ -235,6 +317,15 @@ autoar_format_get_libarchive_read (AutoarFormat format)
   return autoar_format_description[format - 1].libarchive_read;
 }
 
+/**
+ * autoar_format_get_libarchive_write:
+ * @format: an #AutoarFormat
+ *
+ * Gets the function used to set format on the object returned by
+ * archive_write_new().
+ *
+ * Returns: function pointer to the setter function provided by libarchive
+ **/
 AutoarFormatFunc
 autoar_format_get_libarchive_write (AutoarFormat format)
 {
@@ -242,18 +333,41 @@ autoar_format_get_libarchive_write (AutoarFormat format)
   return autoar_format_description[format - 1].libarchive_write;
 }
 
+/**
+ * autoar_filter_last:
+ *
+ * Gets the maximal allowed values of #AutoarFilter
+ *
+ * Returns: maximal allowed values of #AutoarFilter
+ **/
 AutoarFilter
 autoar_filter_last (void)
 {
   return AUTOAR_FILTER_LAST;
 }
 
+/**
+ * autoar_filter_is_valid:
+ * @filter: an #AutoarFilter
+ *
+ * Checks whether an #AutoarFilter is valid.
+ *
+ * Returns: %TRUE if the value of @filter is valid
+ **/
 gboolean
 autoar_filter_is_valid (AutoarFilter filter)
 {
   return (filter > 0 && filter < AUTOAR_FILTER_LAST);
 }
 
+/**
+ * autoar_filter_get_mime_type:
+ * @filter: an #AutoarFilter
+ *
+ * Gets the MIME type of the filter from the internal static data.
+ *
+ * Returns: (transfer none): an MIME type
+ **/
 const char*
 autoar_filter_get_mime_type (AutoarFilter filter)
 {
@@ -261,6 +375,14 @@ autoar_filter_get_mime_type (AutoarFilter filter)
   return autoar_filter_description[filter - 1].mime_type;
 }
 
+/**
+ * autoar_filter_get_extension:
+ * @filter: an #AutoarFilter
+ *
+ * Gets the file name extension of the filter from the internal static data.
+ *
+ * Returns: (transfer none): a file name extension
+ **/
 const char*
 autoar_filter_get_extension (AutoarFilter filter)
 {
@@ -268,6 +390,14 @@ autoar_filter_get_extension (AutoarFilter filter)
   return autoar_filter_description[filter - 1].extension;
 }
 
+/**
+ * autoar_filter_get_description:
+ * @filter: an #AutoarFilter
+ *
+ * Gets description of the filter from the internal static data.
+ *
+ * Returns: (transfer none): description about the filter
+ **/
 const char*
 autoar_filter_get_description (AutoarFilter filter)
 {
@@ -275,6 +405,15 @@ autoar_filter_get_description (AutoarFilter filter)
   return autoar_filter_description[filter - 1].description;
 }
 
+/**
+ * autoar_filter_get_filter_libarchive:
+ * @filter: an #AutoarFilter
+ *
+ * Gets the filter code used by libarchive. You can use the return value
+ * as the argument for archive_write_add_filter().
+ *
+ * Returns: an integer
+ **/
 int
 autoar_filter_get_filter_libarchive (AutoarFilter filter)
 {
@@ -282,6 +421,16 @@ autoar_filter_get_filter_libarchive (AutoarFilter filter)
   return autoar_filter_description[filter - 1].libarchive_filter;
 }
 
+/**
+ * autoar_filter_get_description_libarchive:
+ * @filter: an #AutoarFilter
+ *
+ * Gets description of the filter from libarchive. This function creates
+ * and destroys an archive object in order to get the description string.
+ *
+ * Returns: (transfer full): description about the filter. Free the returned
+ * string with g_free().
+ **/
 gchar*
 autoar_filter_get_description_libarchive (AutoarFilter filter)
 {
@@ -298,6 +447,15 @@ autoar_filter_get_description_libarchive (AutoarFilter filter)
   return str;
 }
 
+/**
+ * autoar_filter_get_libarchive_read:
+ * @filter: an #AutoarFilter
+ *
+ * Gets the function used to add filter on the object returned by
+ * archive_read_new().
+ *
+ * Returns: function pointer to the setter function provided by libarchive
+ **/
 AutoarFilterFunc
 autoar_filter_get_libarchive_read (AutoarFilter filter)
 {
@@ -305,6 +463,15 @@ autoar_filter_get_libarchive_read (AutoarFilter filter)
   return autoar_filter_description[filter - 1].libarchive_read;
 }
 
+/**
+ * autoar_filter_get_libarchive_write:
+ * @filter: an #AutoarFilter
+ *
+ * Gets the function used to add filter on the object returned by
+ * archive_write_new().
+ *
+ * Returns: function pointer to the setter function provided by libarchive
+ **/
 AutoarFilterFunc
 autoar_filter_get_libarchive_write (AutoarFilter filter)
 {
@@ -312,6 +479,21 @@ autoar_filter_get_libarchive_write (AutoarFilter filter)
   return autoar_filter_description[filter - 1].libarchive_write;
 }
 
+/**
+ * autoar_format_filter_get_mime_type:
+ * @format: an #AutoarFormat
+ * @filter: an #AutoarFilter
+ *
+ * Gets the MIME type for an archive @format compressed by
+ * @filter. This function always succeed, but it is not guaranteed
+ * that the returned MIME type exists and can be recognized by applications.
+ * Some combination of format and filter seldom exists in application,
+ * so this function can only generate the string based on some
+ * non-standard rules.
+ *
+ * Returns: (transfer full): an MIME type. Free the returned
+ * string with g_free().
+ **/
 gchar*
 autoar_format_filter_get_mime_type (AutoarFormat format,
                                     AutoarFilter filter)
@@ -339,6 +521,17 @@ autoar_format_filter_get_mime_type (AutoarFormat format,
   }
 }
 
+/**
+ * autoar_format_filter_get_extension:
+ * @format: an #AutoarFormat
+ * @filter: an #AutoarFilter
+ *
+ * Gets the file name extension for an archive @format compressed by
+ * @filter. The first character of the returned string is always '.'
+ *
+ * Returns: (transfer full): a file name extension. Free the returned string
+ * with g_free().
+ **/
 gchar*
 autoar_format_filter_get_extension (AutoarFormat format,
                                     AutoarFilter filter)
@@ -353,6 +546,17 @@ autoar_format_filter_get_extension (AutoarFormat format,
                       NULL);
 }
 
+/**
+ * autoar_format_filter_get_description:
+ * @format: an #AutoarFormat
+ * @filter: an #AutoarFilter
+ *
+ * Gets the description for an archive @format compressed by
+ * @filter using #GContentType and autoar_format_filter_get_mime_type().
+ *
+ * Returns: (transfer full): description about the archive. Free the returned
+ * string with g_free().
+ **/
 gchar*
 autoar_format_filter_get_description (AutoarFormat format,
                                       AutoarFilter filter)
diff --git a/gnome-autoar/autoar-format-filter.h b/gnome-autoar/autoar-format-filter.h
index d01d8c7..f55ce55 100644
--- a/gnome-autoar/autoar-format-filter.h
+++ b/gnome-autoar/autoar-format-filter.h
@@ -31,8 +31,39 @@
 
 G_BEGIN_DECLS
 
+/**
+ * AutoarFormat:
+ * @AUTOAR_FORMAT_ZIP: %ARCHIVE_FORMAT_ZIP: Zip archive
+ * @AUTOAR_FORMAT_TAR: %ARCHIVE_FORMAT_TAR_PAX_RESTRICTED: Tar archive, use
+ *   ustar format is possible. If there are extended headers which cannot be
+ *   represented in the ustar format, libarchive will use pax interchage format
+ *   instead.
+ * @AUTOAR_FORMAT_CPIO: %ARCHIVE_FORMAT_CPIO_POSIX: CPIO archive, POSIX
+ *   standard cpio interchage format.
+ * @AUTOAR_FORMAT_7ZIP: %ARCHIVE_FORMAT_7ZIP: 7-zip archive
+ * @AUTOAR_FORMAT_AR_BSD: %ARCHIVE_FORMAT_AR_BSD: BSD variant of Unix archive
+ *   format. This format does not support storing directories.
+ * @AUTOAR_FORMAT_AR_SVR4: %ARCHIVE_FORMAT_AR_GNU: GNU/SVR4 variant of Unix
+ *   archive format. This format does not support storing directories.
+ * @AUTOAR_FORMAT_CPIO_NEWC: %ARCHIVE_FORMAT_CPIO_SVR4_NOCRC: CPIO archive,
+ *   SVR4 non-CRC variant
+ * @AUTOAR_FORMAT_GNUTAR: %ARCHIVE_FORMAT_TAR_GNUTAR: Tar archive, support
+ *   most popular GNU extensions.
+ * @AUTOAR_FORMAT_ISO9660: %ARCHIVE_FORMAT_ISO9660: Raw CD image
+ * @AUTOAR_FORMAT_PAX: %ARCHIVE_FORMAT_TAR_PAX_INTERCHANGE: Tar archive, use
+ *   pax interchage format
+ * @AUTOAR_FORMAT_USTAR: %ARCHIVE_FORMAT_TAR_USTAR: Tar archive, use old
+ *   ustar format
+ * @AUTOAR_FORMAT_XAR: %ARCHIVE_FORMAT_XAR: Xar archive
+ *
+ * This is a non-negative number which represents formats supported by
+ * libarchive. A libarchive format is a file format which can store many
+ * files as a archive file.
+ **/
 typedef enum {
+  /*< private >*/
   AUTOAR_FORMAT_0, /*< skip >*/
+  /*< public >*/
   AUTOAR_FORMAT_ZIP = 1,   /* .zip */
   AUTOAR_FORMAT_TAR,       /* .tar, pax_restricted */
   AUTOAR_FORMAT_CPIO,      /* .cpio, odc */
@@ -45,11 +76,31 @@ typedef enum {
   AUTOAR_FORMAT_PAX,       /* .tar, pax */
   AUTOAR_FORMAT_USTAR,     /* .tar, ustar */
   AUTOAR_FORMAT_XAR,       /* .xar, xar */
+  /*< private >*/
   AUTOAR_FORMAT_LAST /*< skip >*/
 } AutoarFormat;
 
+/**
+ * AutoarFilter:
+ * @AUTOAR_FILTER_NONE: %ARCHIVE_FILTER_NONE: No filter
+ * @AUTOAR_FILTER_COMPRESS: %ARCHIVE_FILTER_COMPRESS: UNIX-compressed
+ * @AUTOAR_FILTER_GZIP: %ARCHIVE_FILTER_GZIP: Gzip
+ * @AUTOAR_FILTER_BZIP2: %ARCHIVE_FILTER_BZIP2: Bzip2
+ * @AUTOAR_FILTER_XZ: %ARCHIVE_FILTER_XZ: XZ
+ * @AUTOAR_FILTER_LZMA: %ARCHIVE_FILTER_LZMA: LZMA
+ * @AUTOAR_FILTER_LZIP: %ARCHIVE_FILTER_LZIP: Lzip
+ * @AUTOAR_FILTER_LZOP: %ARCHIVE_FILTER_LZOP: LZO
+ * @AUTOAR_FILTER_GRZIP: %ARCHIVE_FILTER_GRZIP: GRZip
+ * @AUTOAR_FILTER_LRZIP: %ARCHIVE_FILTER_LRZIP: Long Range ZIP (lrzip)
+ *
+ * This is a non-negative number which represents filters supported by
+ * libarchive. A libarchive filter is a filter which can convert a
+ * regular file into a compressed file.
+ **/
 typedef enum {
+  /*< private >*/
   AUTOAR_FILTER_0, /*< skip >*/
+  /*< public >*/
   AUTOAR_FILTER_NONE = 1,
   AUTOAR_FILTER_COMPRESS,  /* .Z */
   AUTOAR_FILTER_GZIP,      /* .gz */
@@ -60,11 +111,12 @@ typedef enum {
   AUTOAR_FILTER_LZOP,      /* .lzo */
   AUTOAR_FILTER_GRZIP,     /* .grz */
   AUTOAR_FILTER_LRZIP,     /* .lrz */
+  /*< private >*/
   AUTOAR_FILTER_LAST /*< skip >*/
 } AutoarFilter;
 
-typedef int (*AutoarFormatFunc) (struct archive*);
-typedef int (*AutoarFilterFunc) (struct archive*);
+typedef int (*AutoarFormatFunc) (struct archive *a);
+typedef int (*AutoarFilterFunc) (struct archive *a);
 
 AutoarFormat  autoar_format_last                        (void);
 gboolean      autoar_format_is_valid                    (AutoarFormat format);