alpm.h: use Doxygen-style grouping in documentation
 

---
lib/libalpm/alpm.h | 51 ++++++++++++++++++++++++++++++++++++---------------
1 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 14a2782..0011bb3 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -39,6 +39,13 @@ extern "C" {
* Arch Linux Package Management library
*/

+/**
+ * @addtogroup libalpm Public API
+ *
+ * @brief The libalpm Public API
+ * @{
+ */
+
/*
* Structures
*/
@@ -93,8 +100,10 @@ typedef void (*alpm_cb_totaldl)(off_t total);
typedef int (*alpm_cb_fetch)(const char *url, const char *localpath,
int force);

-/*
- * Options
+/**
+ * @addtogroup alpm_options Options
+ * @{
+ * @brief Libalpm option getters and setters
*/

alpm_cb_log alpm_option_get_logcb(void);
@@ -158,6 +167,8 @@ void alpm_option_set_usedelta(int usedelta);
int alpm_option_get_checkspace(void);
void alpm_option_set_checkspace(int checkspace);

+/** @} */
+
pmdb_t *alpm_option_get_localdb(void);
alpm_list_t *alpm_option_get_syncdbs(void);

@@ -193,8 +204,10 @@ alpm_list_t *alpm_db_get_grpcache(pmdb_t *db);
alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles);
int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason);

-/*
- * Packages
+/**
+ * @addtogroup alpm_packages Package functions
+ * @{
+ * @brief Packages
*/

/* Info parameters */
@@ -407,6 +420,9 @@ int alpm_pkg_has_scriptlet(pmpkg_t *pkg);
off_t alpm_pkg_download_size(pmpkg_t *newpkg);
alpm_list_t *alpm_pkg_unused_deltas(pmpkg_t *pkg);

+/* endgroup alpm_packages */
+/** @} */
+
/*
* Deltas
*/
@@ -430,12 +446,13 @@ alpm_list_t *alpm_find_grp_pkgs(alpm_list_t *dbs, const char *name);

pmpkg_t *alpm_sync_newversion(pmpkg_t *pkg, alpm_list_t *dbs_sync);

-/*
- * Transactions
+/**
+ * @addtogroup alpm_trans Transactions
+ * @{
+ * @brief Transaction-related enums and functions
*/

-
-/* Flags */
+/** Transaction flags */
typedef enum _pmtransflag_t {
PM_TRANS_FLAG_NODEPS = 1,
PM_TRANS_FLAG_FORCE = (1 << 1),
@@ -458,10 +475,6 @@ typedef enum _pmtransflag_t {
} pmtransflag_t;

/**
- * @addtogroup alpm_trans
- * @{
- */
-/**
* @brief Transaction events.
* NULL parameters are passed to in all events unless specified otherwise.
*/
@@ -541,7 +554,6 @@ typedef enum _pmtransevt_t {
/** Disk space usage was computed for a package */
PM_TRANS_EVT_DISKSPACE_DONE,
} pmtransevt_t;
-/*@}*/

/* Transaction Conversations (ie, questions) */
typedef enum _pmtransconv_t {
@@ -584,13 +596,18 @@ int alpm_trans_prepare(alpm_list_t **data);
int alpm_trans_commit(alpm_list_t **data);
int alpm_trans_interrupt(void);
int alpm_trans_release(void);
+/*@}*/

int alpm_sync_sysupgrade(int enable_downgrade);
int alpm_add_pkg(pmpkg_t *pkg);
int alpm_remove_pkg(pmpkg_t *pkg);

-/*
- * Dependencies and conflicts
+/**
+ * @addtogroup alpm_depends Dependency and conflict information
+ * @{
+ *
+ * @brief Helper functions to manage dependency information
+ * structures
*/

/** @brief Types of version constraints in dependency specs. */
@@ -656,6 +673,8 @@ const char *alpm_dep_get_version(const pmdepend_t *dep);
*/
char *alpm_dep_compute_string(const pmdepend_t *dep);

+// @}
+
/*
* File conflicts
*/
@@ -744,6 +763,8 @@ extern enum _pmerrno_t pm_errno;
const char *alpm_strerror(int err);
const char *alpm_strerrorlast(void);

+/** @} */
+
#ifdef __cplusplus
}
#endif
--
1.7.4.1

alpm.h: use Doxygen-style grouping in documentation
 

Looks good- if you could get the existing 'Database Functions' group
under Public API that might be good too, since a lot of those are
double-covered now in the HTML docs I just generated. And kill the
alpm_misc group totally, just let those show up under Public API.

I'd also use Title Casing for all the group names.

-Dan

On Tue, Mar 1, 2011 at 2:18 PM, Rémy Oudompheng
<remyoudompheng@gmail.com> wrote:
> ---
> *lib/libalpm/alpm.h | * 51 ++++++++++++++++++++++++++++++++++++---------------
> *1 files changed, 36 insertions(+), 15 deletions(-)
>
> diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
> index 14a2782..0011bb3 100644
> --- a/lib/libalpm/alpm.h
> +++ b/lib/libalpm/alpm.h
> @@ -39,6 +39,13 @@ extern "C" {
> ** Arch Linux Package Management library
> **/
>
> +/**
> + * @addtogroup libalpm Public API
> + *
> + * @brief The libalpm Public API
> + * @{
> + */
> +
> */*
> ** Structures
> **/
> @@ -93,8 +100,10 @@ typedef void (*alpm_cb_totaldl)(off_t total);
> *typedef int (*alpm_cb_fetch)(const char *url, const char *localpath,
> * * * * * * * *int force);
>
> -/*
> - * Options
> +/**
> + * @addtogroup alpm_options Options
> + * @{
> + * @brief Libalpm option getters and setters
> **/
>
> *alpm_cb_log alpm_option_get_logcb(void);
> @@ -158,6 +167,8 @@ void alpm_option_set_usedelta(int usedelta);
> *int alpm_option_get_checkspace(void);
> *void alpm_option_set_checkspace(int checkspace);
>
> +/** @} */
> +
> *pmdb_t *alpm_option_get_localdb(void);
> *alpm_list_t *alpm_option_get_syncdbs(void);
>
> @@ -193,8 +204,10 @@ alpm_list_t *alpm_db_get_grpcache(pmdb_t *db);
> *alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles);
> *int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason);
>
> -/*
> - * Packages
> +/**
> + * @addtogroup alpm_packages Package functions
> + * @{
> + * @brief Packages
> **/
>
> */* Info parameters */
> @@ -407,6 +420,9 @@ int alpm_pkg_has_scriptlet(pmpkg_t *pkg);
> *off_t alpm_pkg_download_size(pmpkg_t *newpkg);
> *alpm_list_t *alpm_pkg_unused_deltas(pmpkg_t *pkg);
>
> +/* endgroup alpm_packages */
> +/** @} */
> +
> */*
> ** Deltas
> **/
> @@ -430,12 +446,13 @@ alpm_list_t *alpm_find_grp_pkgs(alpm_list_t *dbs, const char *name);
>
> *pmpkg_t *alpm_sync_newversion(pmpkg_t *pkg, alpm_list_t *dbs_sync);
>
> -/*
> - * Transactions
> +/**
> + * @addtogroup alpm_trans Transactions
> + * @{
> + * @brief Transaction-related enums and functions
> **/
>
> -
> -/* Flags */
> +/** Transaction flags */
> *typedef enum _pmtransflag_t {
> * * * *PM_TRANS_FLAG_NODEPS = 1,
> * * * *PM_TRANS_FLAG_FORCE = (1 << 1),
> @@ -458,10 +475,6 @@ typedef enum _pmtransflag_t {
> *} pmtransflag_t;
>
> */**
> - * @addtogroup alpm_trans
> - * @{
> - */
> -/**
> ** @brief Transaction events.
> ** NULL parameters are passed to in all events unless specified otherwise.
> **/
> @@ -541,7 +554,6 @@ typedef enum _pmtransevt_t {
> * * * */** Disk space usage was computed for a package */
> * * * *PM_TRANS_EVT_DISKSPACE_DONE,
> *} pmtransevt_t;
> -/*@}*/
>
> */* Transaction Conversations (ie, questions) */
> *typedef enum _pmtransconv_t {
> @@ -584,13 +596,18 @@ int alpm_trans_prepare(alpm_list_t **data);
> *int alpm_trans_commit(alpm_list_t **data);
> *int alpm_trans_interrupt(void);
> *int alpm_trans_release(void);
> +/*@}*/
>
> *int alpm_sync_sysupgrade(int enable_downgrade);
> *int alpm_add_pkg(pmpkg_t *pkg);
> *int alpm_remove_pkg(pmpkg_t *pkg);
>
> -/*
> - * Dependencies and conflicts
> +/**
> + * @addtogroup alpm_depends Dependency and conflict information
> + * @{
> + *
> + * @brief Helper functions to manage dependency information
> + * * * * *structures
> **/
>
> */** @brief Types of version constraints in dependency specs. */
> @@ -656,6 +673,8 @@ const char *alpm_dep_get_version(const pmdepend_t *dep);
> **/
> *char *alpm_dep_compute_string(const pmdepend_t *dep);
>
> +// @}
> +
> */*
> ** File conflicts
> **/
> @@ -744,6 +763,8 @@ extern enum _pmerrno_t pm_errno;
> *const char *alpm_strerror(int err);
> *const char *alpm_strerrorlast(void);
>
> +/** @} */
> +
> *#ifdef __cplusplus
> *}
> *#endif
> --
> 1.7.4.1
>
>
>