[pacman-dev] [PATCH 2/4] Clean up doxygen markup for the libalpm groups.
Jeremy Heiner
scalaprotractor at gmail.com
Sat Dec 21 23:22:24 EST 2013
In the recent past only the 2 public .h files were INPUT to doxygen,
and so the markup in those 2 files received a little maintenance. But
there is also markup in some of the .c files (which the previous
commit added back to INPUT) that had not received maintenance. This
brings them back into sync.
Most notably the ids for the groups in the alpm.h file got changed to
"alpm_api_<*>", while the .c files kept "alpm_<*>", causing doxygen to
produce two nearly identical copies of those groups. The older .c ids
and the @defgroup / @addtogroup @{ @} commands were retired from:
{alpm,alpm_list,be_sync,db,delta,log,package,trans,util}.c
leaving the group definition solely to the .h files.
In alpm_list.h the non-doxygen-markup comments indicating grouping
were "upgraded" to be @name @{ @} groups. alpm_list_fn_cmp had to be
moved to get it out of the middle of the "allocation" group, which was
renamed "deallocation" to be more accurate.
In alpm.h an unbalanced @} was found (adding "end group <*>" comments
helped). A Signatures group was added. And the alpm_list_t group was
moved from being a sibling of the Public API to being a child of it.
Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com>
---
lib/libalpm/alpm.c | 11 -----------
lib/libalpm/alpm.h | 34 ++++++++++++++++++++--------------
lib/libalpm/alpm_list.c | 7 ++-----
lib/libalpm/alpm_list.h | 36 ++++++++++++++++++++++++++++++------
lib/libalpm/be_sync.c | 1 -
lib/libalpm/db.c | 6 +-----
lib/libalpm/delta.c | 7 -------
lib/libalpm/log.c | 5 +----
lib/libalpm/package.c | 5 +----
lib/libalpm/trans.c | 5 +----
lib/libalpm/util.c | 2 --
11 files changed, 56 insertions(+), 63 deletions(-)
diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c
index 878c38b..28d2f06 100644
--- a/lib/libalpm/alpm.c
+++ b/lib/libalpm/alpm.c
@@ -32,11 +32,6 @@
#include "log.h"
#include "util.h"
-/** \addtogroup alpm_interface Interface Functions
- * @brief Functions to initialize and release libalpm
- * @{
- */
-
/** Initializes the library.
* Creates handle, connects to database and creates lockfile.
* This must be called before any other functions are called.
@@ -123,12 +118,6 @@ int SYMEXPORT alpm_release(alpm_handle_t *myhandle)
return ret;
}
-/** @} */
-
-/** @defgroup alpm_misc Miscellaneous Functions
- * @brief Various libalpm functions
- */
-
/** Get the version of library.
* @return the library version, e.g. "6.0.4"
* */
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index e9b0feb..94ad89f 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -598,7 +598,7 @@ int alpm_option_set_local_file_siglevel(alpm_handle_t *handle, alpm_siglevel_t l
alpm_siglevel_t alpm_option_get_remote_file_siglevel(alpm_handle_t *handle);
int alpm_option_set_remote_file_siglevel(alpm_handle_t *handle, alpm_siglevel_t level);
-/** @} */
+/** @} */ /* end group alpm_api_options */
/** @addtogroup alpm_api_databases Database Functions
* Functions to query and manipulate the database of libalpm.
@@ -731,7 +731,7 @@ int alpm_db_set_usage(alpm_db_t *db, alpm_db_usage_t usage);
*/
int alpm_db_get_usage(alpm_db_t *db, alpm_db_usage_t *usage);
-/** @} */
+/** @} */ /* end group alpm_api_databases */
/** @addtogroup alpm_api_packages Package Functions
* Functions to manipulate libalpm packages
@@ -1057,8 +1057,7 @@ alpm_list_t *alpm_pkg_unused_deltas(alpm_pkg_t *pkg);
int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason);
-/* End of alpm_pkg */
-/** @} */
+/** @} */ /* end group alpm_api_packages */
/*
* Filelists
@@ -1074,9 +1073,8 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason);
*/
alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path);
-/*
- * Signatures
- */
+/** @addtogroup alpm_api_pgp Signatures
+ * @{ */
int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist);
@@ -1090,6 +1088,8 @@ int alpm_decode_signature(const char *base64_data,
int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
const unsigned char *sig, const size_t len, alpm_list_t **keys);
+/** @} */ /* end group alpm_api_pgp */
+
/*
* Groups
*/
@@ -1197,7 +1197,8 @@ int alpm_trans_interrupt(alpm_handle_t *handle);
* @return 0 on success, -1 on error (pm_errno is set accordingly)
*/
int alpm_trans_release(alpm_handle_t *handle);
-/** @} */
+
+/** @} */ /* end group alpm_api_trans */
/** @name Common Transactions */
/** @{ */
@@ -1247,9 +1248,7 @@ alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist);
*/
char *alpm_dep_compute_string(const alpm_depend_t *dep);
-/** @} */
-
-/** @} */
+/** @} */ /* end group alpm_api_depends */
/*
* Helpers
@@ -1335,8 +1334,10 @@ alpm_errno_t alpm_errno(alpm_handle_t *handle);
/** Returns the string corresponding to an error number. */
const char *alpm_strerror(alpm_errno_t err);
-/* End of alpm_api_errors */
-/** @} */
+/** @} */ /* end group alpm_api_errors */
+
+/** @name Functions to initialize and release libalpm
+ * @{ */
alpm_handle_t *alpm_initialize(const char *root, const char *dbpath,
alpm_errno_t *err);
@@ -1351,9 +1352,14 @@ enum alpm_caps {
const char *alpm_version(void);
enum alpm_caps alpm_capabilities(void);
-/* End of alpm_api */
/** @} */
+/**
+ * @addtogroup alpm_api_list
+ * @ingroup alpm_api
+ */
+/** @} */ /* end group alpm_api */
+
#ifdef __cplusplus
}
#endif
diff --git a/lib/libalpm/alpm_list.c b/lib/libalpm/alpm_list.c
index a3c73aa..11410d5 100644
--- a/lib/libalpm/alpm_list.c
+++ b/lib/libalpm/alpm_list.c
@@ -33,14 +33,13 @@
#define SYMHIDDEN __attribute__((visibility("internal")))
/**
- * @addtogroup alpm_list List Functions
+ * @addtogroup alpm_api_list List Functions
* @brief Functions to manipulate alpm_list_t lists.
*
* These functions are designed to create, destroy, and modify lists of
* type alpm_list_t. This is an internal list type used by libalpm that is
* publicly exposed for use by frontends if desired.
- *
- * @{ */
+ */
/* Allocation */
@@ -788,6 +787,4 @@ void SYMEXPORT *alpm_list_to_array(const alpm_list_t *list, size_t n,
return array;
}
-/** @} */
-
/* vim: set ts=2 sw=2 noet: */
diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h
index 3f3566b..c38c496 100644
--- a/lib/libalpm/alpm_list.h
+++ b/lib/libalpm/alpm_list.h
@@ -30,6 +30,9 @@
extern "C" {
#endif
+/** @addtogroup alpm_api_list
+ * @{ */
+
/**
* @brief Linked list type used by libalpm.
*
@@ -46,16 +49,28 @@ typedef struct __alpm_list_t {
struct __alpm_list_t *next;
} alpm_list_t;
+/**
+ * @brief item comparison callback
+ */
+typedef int (*alpm_list_fn_cmp)(const void *, const void *);
+
+/** @name Deallocation
+ * @{ */
+
#define FREELIST(p) do { alpm_list_free_inner(p, free); alpm_list_free(p); p = NULL; } while(0)
-typedef void (*alpm_list_fn_free)(void *); /* item deallocation callback */
-typedef int (*alpm_list_fn_cmp)(const void *, const void *); /* item comparison callback */
+/**
+ * @brief item deallocation callback
+ */
+typedef void (*alpm_list_fn_free)(void *);
-/* allocation */
void alpm_list_free(alpm_list_t *list);
void alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn);
-/* item mutators */
+/** @} */
+/** @name Mutators
+ * @{ */
+
alpm_list_t *alpm_list_add(alpm_list_t *list, void *data);
alpm_list_t *alpm_list_add_sorted(alpm_list_t *list, void *data, alpm_list_fn_cmp fn);
alpm_list_t *alpm_list_join(alpm_list_t *first, alpm_list_t *second);
@@ -70,13 +85,19 @@ alpm_list_t *alpm_list_copy(const alpm_list_t *list);
alpm_list_t *alpm_list_copy_data(const alpm_list_t *list, size_t size);
alpm_list_t *alpm_list_reverse(alpm_list_t *list);
-/* item accessors */
+/** @} */
+/** @name Accessors
+ * @{ */
+
alpm_list_t *alpm_list_nth(const alpm_list_t *list, size_t n);
alpm_list_t *alpm_list_next(const alpm_list_t *list);
alpm_list_t *alpm_list_previous(const alpm_list_t *list);
alpm_list_t *alpm_list_last(const alpm_list_t *list);
-/* misc */
+/** @} */
+/** @name Misc
+ * @{ */
+
size_t alpm_list_count(const alpm_list_t *list);
void *alpm_list_find(const alpm_list_t *haystack, const void *needle, alpm_list_fn_cmp fn);
void *alpm_list_find_ptr(const alpm_list_t *haystack, const void *needle);
@@ -86,6 +107,9 @@ void alpm_list_diff_sorted(const alpm_list_t *left, const alpm_list_t *right,
alpm_list_fn_cmp fn, alpm_list_t **onlyleft, alpm_list_t **onlyright);
void *alpm_list_to_array(const alpm_list_t *list, size_t n, size_t size);
+/** @} */
+/** @} */
+
#ifdef __cplusplus
}
#endif
diff --git a/lib/libalpm/be_sync.c b/lib/libalpm/be_sync.c
index 123d953..de09471 100644
--- a/lib/libalpm/be_sync.c
+++ b/lib/libalpm/be_sync.c
@@ -158,7 +158,6 @@ valid:
* }
* @endcode
*
- * @ingroup alpm_databases
* @note After a successful update, the \link alpm_db_get_pkgcache()
* package cache \endlink will be invalidated
* @param force if true, then forces the update, otherwise update only in case
diff --git a/lib/libalpm/db.c b/lib/libalpm/db.c
index 2069a7b..35bf2cc 100644
--- a/lib/libalpm/db.c
+++ b/lib/libalpm/db.c
@@ -37,9 +37,8 @@
#include "package.h"
#include "group.h"
-/** \addtogroup alpm_databases Database Functions
+/** @file
* @brief Functions to query and manipulate the database of libalpm
- * @{
*/
/** Register a sync database of packages. */
@@ -322,9 +321,6 @@ int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, alpm_db_usage_t *usage)
return 0;
}
-
-/** @} */
-
alpm_db_t *_alpm_db_new(const char *treename, int is_local)
{
alpm_db_t *db;
diff --git a/lib/libalpm/delta.c b/lib/libalpm/delta.c
index 2da1496..a8ffc94 100644
--- a/lib/libalpm/delta.c
+++ b/lib/libalpm/delta.c
@@ -256,11 +256,6 @@ static alpm_list_t *find_unused(alpm_list_t *deltas, const char *to, off_t quota
return unused;
}
-/** \addtogroup alpm_deltas Delta Functions
- * @brief Functions to manipulate libalpm deltas
- * @{
- */
-
alpm_list_t SYMEXPORT *alpm_pkg_unused_deltas(alpm_pkg_t *pkg)
{
ASSERT(pkg != NULL, return NULL);
@@ -268,8 +263,6 @@ alpm_list_t SYMEXPORT *alpm_pkg_unused_deltas(alpm_pkg_t *pkg)
pkg->size * pkg->handle->deltaratio);
}
-/** @} */
-
#define NUM_MATCHES 6
/** Parses the string representation of a alpm_delta_t object.
diff --git a/lib/libalpm/log.c b/lib/libalpm/log.c
index 271bd00..ff4505b 100644
--- a/lib/libalpm/log.c
+++ b/lib/libalpm/log.c
@@ -28,9 +28,8 @@
#include "util.h"
#include "alpm.h"
-/** \addtogroup alpm_log Logging Functions
+/** @file
* @brief Functions to log using libalpm
- * @{
*/
/** A printf-like function for logging.
@@ -70,8 +69,6 @@ int SYMEXPORT alpm_logaction(alpm_handle_t *handle, const char *prefix,
return ret;
}
-/** @} */
-
void _alpm_log(alpm_handle_t *handle, alpm_loglevel_t flag, const char *fmt, ...)
{
va_list args;
diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c
index 1294f8e..3317a95 100644
--- a/lib/libalpm/package.c
+++ b/lib/libalpm/package.c
@@ -35,9 +35,8 @@
#include "handle.h"
#include "deps.h"
-/** \addtogroup alpm_packages Package Functions
+/** @file
* @brief Functions to manipulate libalpm packages
- * @{
*/
/** Free a package. */
@@ -504,8 +503,6 @@ alpm_list_t SYMEXPORT *alpm_pkg_compute_optionalfor(alpm_pkg_t *pkg)
}
-/** @} */
-
alpm_file_t *_alpm_file_copy(alpm_file_t *dest,
const alpm_file_t *src)
{
diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c
index a795a1f..2148aad 100644
--- a/lib/libalpm/trans.c
+++ b/lib/libalpm/trans.c
@@ -40,9 +40,8 @@
#include "sync.h"
#include "alpm.h"
-/** \addtogroup alpm_trans Transaction Functions
+/** @file
* @brief Functions to manipulate libalpm transactions
- * @{
*/
/** Initialize the transaction. */
@@ -226,8 +225,6 @@ int SYMEXPORT alpm_trans_release(alpm_handle_t *handle)
return 0;
}
-/** @} */
-
void _alpm_trans_free(alpm_trans_t *trans)
{
if(trans == NULL) {
diff --git a/lib/libalpm/util.c b/lib/libalpm/util.c
index 40a5ebd..da7f51f 100644
--- a/lib/libalpm/util.c
+++ b/lib/libalpm/util.c
@@ -886,7 +886,6 @@ static char *hex_representation(unsigned char *bytes, size_t size)
/** Get the md5 sum of file.
* @param filename name of the file
* @return the checksum on success, NULL on error
- * @addtogroup alpm_misc
*/
char SYMEXPORT *alpm_compute_md5sum(const char *filename)
{
@@ -905,7 +904,6 @@ char SYMEXPORT *alpm_compute_md5sum(const char *filename)
/** Get the sha256 sum of file.
* @param filename name of the file
* @return the checksum on success, NULL on error
- * @addtogroup alpm_misc
*/
char SYMEXPORT *alpm_compute_sha256sum(const char *filename)
{
--
1.8.5.2
More information about the pacman-dev
mailing list