[pacman-dev] [PATCH 2/2] Add missing documentation to public API functions.
Rémy Oudompheng
remyoudompheng at gmail.com
Sun Apr 17 08:01:41 EDT 2011
Signed-off-by: Rémy Oudompheng <remy at archlinux.org>
---
lib/libalpm/alpm.h | 7 +++++++
lib/libalpm/handle.c | 28 ++++++++++++++++++++++++++++
lib/libalpm/package.c | 1 +
lib/libalpm/remove.c | 4 ++++
lib/libalpm/trans.c | 3 +++
5 files changed, 43 insertions(+), 0 deletions(-)
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 61c8cdb..582b2c0 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -85,9 +85,16 @@ int alpm_logaction(const char *fmt, ...);
* Downloading
*/
+/** Type of download progress callbacks.
+ * @param filename the name of the file being downloaded
+ * @param xfered the number of transferred bytes
+ * @param total the total number of bytes to transfer
+ */
typedef void (*alpm_cb_download)(const char *filename,
off_t xfered, off_t total);
+
typedef void (*alpm_cb_totaldl)(off_t total);
+
/** A callback for downloading files
* @param url the URL of the file to be downloaded
* @param localpath the directory to which the file should be downloaded
diff --git a/lib/libalpm/handle.c b/lib/libalpm/handle.c
index 917441e..34e0d4f 100644
--- a/lib/libalpm/handle.c
+++ b/lib/libalpm/handle.c
@@ -191,6 +191,7 @@ int SYMEXPORT alpm_option_get_usesyslog()
return handle->usesyslog;
}
+/** Returns the list of packages names in the NoUpgrades list. */
alpm_list_t SYMEXPORT *alpm_option_get_noupgrades()
{
if (handle == NULL) {
@@ -200,6 +201,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_noupgrades()
return handle->noupgrade;
}
+/** Returns the list of packages names in the NoExtract list. */
alpm_list_t SYMEXPORT *alpm_option_get_noextracts()
{
if (handle == NULL) {
@@ -209,6 +211,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_noextracts()
return handle->noextract;
}
+/** Returns the list of packages in the ignore list. */
alpm_list_t SYMEXPORT *alpm_option_get_ignorepkgs()
{
if (handle == NULL) {
@@ -218,6 +221,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_ignorepkgs()
return handle->ignorepkg;
}
+/** Returns the list of groups in the ignore list. */
alpm_list_t SYMEXPORT *alpm_option_get_ignoregrps()
{
if (handle == NULL) {
@@ -237,6 +241,7 @@ const char SYMEXPORT *alpm_option_get_arch()
return handle->arch;
}
+/** Returns whether libalpm uses deltas (0 is FALSE, TRUE otherwise, -1 on error). */
int SYMEXPORT alpm_option_get_usedelta()
{
if (handle == NULL) {
@@ -285,6 +290,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_syncdbs()
return handle->dbs_sync;
}
+/** Sets the logging callback. */
void SYMEXPORT alpm_option_set_logcb(alpm_cb_log cb)
{
if (handle == NULL) {
@@ -294,6 +300,7 @@ void SYMEXPORT alpm_option_set_logcb(alpm_cb_log cb)
handle->logcb = cb;
}
+/** Sets the callback download progress callback. */
void SYMEXPORT alpm_option_set_dlcb(alpm_cb_download cb)
{
if (handle == NULL) {
@@ -303,6 +310,7 @@ void SYMEXPORT alpm_option_set_dlcb(alpm_cb_download cb)
handle->dlcb = cb;
}
+/** Sets the download callback. */
void SYMEXPORT alpm_option_set_fetchcb(alpm_cb_fetch cb)
{
if (handle == NULL) {
@@ -312,6 +320,7 @@ void SYMEXPORT alpm_option_set_fetchcb(alpm_cb_fetch cb)
handle->fetchcb = cb;
}
+/** Sets the callback used to report total download size. */
void SYMEXPORT alpm_option_set_totaldlcb(alpm_cb_totaldl cb)
{
if (handle == NULL) {
@@ -321,6 +330,7 @@ void SYMEXPORT alpm_option_set_totaldlcb(alpm_cb_totaldl cb)
handle->totaldlcb = cb;
}
+/** Sets the root directory of the destination filesystem. */
int SYMEXPORT alpm_option_set_root(const char *root)
{
struct stat st;
@@ -363,6 +373,7 @@ int SYMEXPORT alpm_option_set_root(const char *root)
return(0);
}
+/** Sets the path of the database. */
int SYMEXPORT alpm_option_set_dbpath(const char *dbpath)
{
struct stat st;
@@ -432,6 +443,7 @@ int SYMEXPORT alpm_option_add_cachedir(const char *cachedir)
return(0);
}
+/** Sets the list of package cache directories. */
void SYMEXPORT alpm_option_set_cachedirs(alpm_list_t *cachedirs)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
@@ -463,6 +475,7 @@ int SYMEXPORT alpm_option_remove_cachedir(const char *cachedir)
return(0);
}
+/** Sets the path of the file used for logging. */
int SYMEXPORT alpm_option_set_logfile(const char *logfile)
{
char *oldlogfile = handle->logfile;
@@ -490,18 +503,23 @@ int SYMEXPORT alpm_option_set_logfile(const char *logfile)
return(0);
}
+/** Sets whether to use syslog for logging. */
void SYMEXPORT alpm_option_set_usesyslog(int usesyslog)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
handle->usesyslog = usesyslog;
}
+/** Adds a single package to the no-upgrade list. */
void SYMEXPORT alpm_option_add_noupgrade(const char *pkg)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
handle->noupgrade = alpm_list_add(handle->noupgrade, strdup(pkg));
}
+/** Sets the no-upgrade list.
+ * @param noupgrade a list of strings
+ */
void SYMEXPORT alpm_option_set_noupgrades(alpm_list_t *noupgrade)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
@@ -509,6 +527,9 @@ void SYMEXPORT alpm_option_set_noupgrades(alpm_list_t *noupgrade)
if(noupgrade) handle->noupgrade = noupgrade;
}
+/** Removes a package name from the no-upgrade list.
+ * @return 1 on success, 0 if the group is not in the list, -1 on error
+ */
int SYMEXPORT alpm_option_remove_noupgrade(const char *pkg)
{
char *vdata = NULL;
@@ -521,12 +542,16 @@ int SYMEXPORT alpm_option_remove_noupgrade(const char *pkg)
return(0);
}
+/** Adds a single package to the no-extract list. */
void SYMEXPORT alpm_option_add_noextract(const char *pkg)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
handle->noextract = alpm_list_add(handle->noextract, strdup(pkg));
}
+/** Sets the no-extract list.
+ * @param noupgrade a list of strings
+ */
void SYMEXPORT alpm_option_set_noextracts(alpm_list_t *noextract)
{
ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL));
@@ -534,6 +559,9 @@ void SYMEXPORT alpm_option_set_noextracts(alpm_list_t *noextract)
if(noextract) handle->noextract = noextract;
}
+/** Removes a package name from the no-extract list.
+ * @return 1 on success, 0 if the group is not in the list, -1 on error
+ */
int SYMEXPORT alpm_option_remove_noextract(const char *pkg)
{
char *vdata = NULL;
diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c
index 9be2fcb..0458993 100644
--- a/lib/libalpm/package.c
+++ b/lib/libalpm/package.c
@@ -436,6 +436,7 @@ int SYMEXPORT alpm_pkg_changelog_close(const pmpkg_t *pkg, void *fp)
return pkg->ops->changelog_close(pkg, fp);
}
+/** Returns whether the package has an install scriptlet (0 is FALSE, TRUE otherwise). */
int SYMEXPORT alpm_pkg_has_scriptlet(pmpkg_t *pkg)
{
return pkg->ops->has_scriptlet(pkg);
diff --git a/lib/libalpm/remove.c b/lib/libalpm/remove.c
index 7c8a99f..eafacdd 100644
--- a/lib/libalpm/remove.c
+++ b/lib/libalpm/remove.c
@@ -46,6 +46,10 @@
#include "handle.h"
#include "alpm.h"
+/** Add a package removal action to the transaction.
+ * @param pkg the package to uninstall
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
int SYMEXPORT alpm_remove_pkg(pmpkg_t *pkg)
{
pmtrans_t *trans;
diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c
index bcb8d14..c711705 100644
--- a/lib/libalpm/trans.c
+++ b/lib/libalpm/trans.c
@@ -462,6 +462,9 @@ cleanup:
return(retval);
}
+/** Returns the bitfield of flags for the current transaction.
+ * @sa _pmtransflag_t
+ */
int SYMEXPORT alpm_trans_get_flags()
{
/* Sanity checks */
--
1.7.4.4
More information about the pacman-dev
mailing list