From 35718e676c590b0dbe2e7b1d300e45835787f0a7 Mon Sep 17 00:00:00 2001
From: Juan RP <xtraeme@voidlinux.eu>
Date: Fri, 30 Oct 2015 13:18:32 +0100
Subject: [PATCH] Document alternatives in the API.

---
 include/xbps.h.in          | 41 ++++++++++++++++++++++++++++++++++----
 lib/package_alternatives.c |  8 ++++++++
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/include/xbps.h.in b/include/xbps.h.in
index 20398d02..13923eb7 100644
--- a/include/xbps.h.in
+++ b/include/xbps.h.in
@@ -639,10 +639,6 @@ void xbps_dbg_printf_append(struct xbps_handle *, const char *, ...);
 void xbps_error_printf(const char *, ...);
 void xbps_warn_printf(const char *, ...);
 
-int xbps_alternatives_set(struct xbps_handle *, const char *, const char *);
-int xbps_alternatives_register(struct xbps_handle *, xbps_dictionary_t);
-int xbps_alternatives_unregister(struct xbps_handle *, xbps_dictionary_t);
-
 /**
  * Initialize the XBPS library with the following steps:
  *
@@ -933,6 +929,43 @@ int xbps_pkg_exec_script(struct xbps_handle *xhp,
 
 /*@}*/
 
+/** @addtogroup alternatives */
+/*@{*/
+
+/**
+ * Sets all alternatives provided by this \a pkg, or only those
+ * set by a \a group.
+ *
+ * @param[in] xhp The pointer to the xbps_handle struct.
+ * @param[in] pkg Package name to match.
+ * @param[in] group Alternatives group to match.
+ *
+ * @return 0 on success, or an errno value otherwise.
+ */
+int xbps_alternatives_set(struct xbps_handle *xhp, const char *pkg, const char *group);
+
+/**
+ * Registers all alternative groups provided by a package.
+ *
+ * @param[in] xhp The pointer to the xbps_handle struct.
+ * @param[in] pkgd Package dictionary as stored in the transaction dictionary.
+ *
+ * @return 0 on success, or an errno value otherwise.
+ */
+int xbps_alternatives_register(struct xbps_handle *xhp, xbps_dictionary_t pkgd);
+
+/**
+ * Unregisters all alternative groups provided by a package.
+ *
+ * @param[in] xhp The pointer to the xbps_handle struct.
+ * @param[in] pkgd Package dictionary as stored in the transaction dictionary.
+ *
+ * @return 0 on success, or an errno value otherwise.
+ */
+int xbps_alternatives_unregister(struct xbps_handle *xhp, xbps_dictionary_t pkgd);
+
+/*@}*/
+
 /** @addtogroup plist */
 /*@{*/
 
diff --git a/lib/package_alternatives.c b/lib/package_alternatives.c
index 02b42e37..71f0fec0 100644
--- a/lib/package_alternatives.c
+++ b/lib/package_alternatives.c
@@ -31,6 +31,14 @@
 
 #include "xbps_api_impl.h"
 
+/**
+ * @file lib/package_alternatives.c
+ * @brief Alternatives generic routines
+ * @defgroup alternatives Alternatives generic functions
+ *
+ * These functions implement the alternatives framework.
+ */
+
 /*
  * XXX TODO: relative symlinks.
  */