Improve API documentation round 1.

lib/package_unpack.c

@@ -35,38 +35,6 @@
 
 #include "xbps_api_impl.h"
 
-/**
- * @file lib/package_unpack.c
- * @brief Binary package file unpacking routines
- * @defgroup unpack Binary package file unpacking functions
- *
- * Unpacking a binary package involves the following steps:
- *  - Its <b>pre-install</b> target in the INSTALL script is executed
- *    (if available).
- *  - Metadata files are extracted.
- *  - All other kind of files on archive are extracted.
- *  - Handles configuration files by taking care of updating them with
- *    new versions if necessary and to not overwrite modified ones.
- *  - Files from installed package are compared with new package and
- *    obsolete files are removed.
- *  - Finally its state is set to XBPS_PKG_STATE_UNPACKED.
- *
- * The following image shown below represents a transaction dictionary
- * returned by xbps_transaction_prepare():
- *
- * @image html images/xbps_transaction_dictionary.png
- *
- * Legend:
- *   - <b>Salmon filled box</b>: The transaction dictionary.
- *   - <b>White filled box</b>: mandatory objects.
- *   - <b>Grey filled box</b>: optional objects.
- *   - <b>Green filled box</b>: possible value set in the object, only one of
- *     them is set.
- *
- * Text inside of white boxes are the key associated with the object, its
- * data type is specified on its edge, i.e string, array, integer, dictionary.
- */
-
 static int
 set_extract_flags(void)
 {

lib/pkgdb.c

@@ -31,6 +31,29 @@
 
 #include "xbps_api_impl.h"
 
+/**
+ * @file lib/pkgdb.c
+ * @brief Package database handling routines
+ * @defgroup pkgdb Package database handling functions
+ *
+ * Functions to manipulate the main package database plist file (pkgdb).
+ *
+ * The following image shown below shows the proplib structure used
+ * by the main package database plist:
+ *
+ * @image html images/xbps_pkgdb_array.png
+ *
+ * Legend:
+ *  - <b>Salmon filled box</b>: \a XBPS_PKGDB file internalized.
+ *  - <b>White filled box</b>: mandatory objects.
+ *  - <b>Grey filled box</b>: optional objects.
+ *  - <b>Green filled box</b>: possible value set in the object, only one
+ *    of them is set.
+ *
+ * Text inside of white boxes are the key associated with the object, its
+ * data type is specified on its edge, i.e array, bool, integer, string,
+ * dictionary.
+ */
 int HIDDEN
 xbps_pkgdb_init(struct xbps_handle *xhp)
 {

lib/transaction_commit.c

@@ -35,6 +35,27 @@
 
 #include "xbps_api_impl.h"
 
+/**
+ * @file lib/transaction_commit.c
+ * @brief Transaction handling routines
+ * @defgroup transaction Transaction handling functions
+ *
+ * The following image shows off the full transaction dictionary returned
+ * by xbps_transaction_prepare().
+ *
+ * @image html images/xbps_transaction_dictionary.png
+ *
+ * Legend:
+ *  - <b>Salmon bg box</b>: The transaction dictionary.
+ *  - <b>White bg box</b>: mandatory objects.
+ *  - <b>Grey bg box</b>: optional objects.
+ *  - <b>Green bg box</b>: possible value set in the object, only one of them
+ *    will be set.
+ *
+ * Text inside of white boxes are the key associated with the object, its
+ * data type is specified on its edge, i.e string, array, integer, dictionary.
+ */
+
 static int
 check_binpkgs_hash(prop_object_iterator_t iter)
 {

lib/transaction_dictionary.c

@@ -34,7 +34,7 @@
 /**
  * @file lib/transaction_dictionary.c
  * @brief Transaction handling routines
- * @defgroup transdict Transaction handling functions
+ * @defgroup transaction Transaction handling functions
  *
  * The following image shows off the full transaction dictionary returned
  * by xbps_transaction_prepare().

lib/transaction_ops.c

@@ -33,8 +33,8 @@
 
 /**
  * @file lib/transaction_ops.c
- * @brief Transaction package handling routines
- * @defgroup repo_pkgs Transaction package handling functions
+ * @brief Transaction handling routines
+ * @defgroup transaction Transaction handling functions
  *
  * The following image shows off the full transaction dictionary returned
  * by xbps_transaction_prepare().