Improve API documentation round 1.

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)
 {