The following commit has been merged in the master branch:
commit e000e4a109b95bc43e558e2f53bc85bc63d3177d
Author: Guillem Jover <[email protected]>
Date: Sun Oct 11 16:33:21 2009 +0200
Document some of the code with JavaDoc
diff --git a/lib/dpkg/pkg-array.c b/lib/dpkg/pkg-array.c
index 5a3ad9e..ae446a5 100644
--- a/lib/dpkg/pkg-array.c
+++ b/lib/dpkg/pkg-array.c
@@ -31,6 +31,11 @@
#include <dpkg/dpkg-db.h>
#include <dpkg/pkg-array.h>
+/**
+ * Initialize a package array from the package database.
+ *
+ * @param a The array to initialize.
+ */
void
pkg_array_init_from_db(struct pkg_array *a)
{
@@ -49,12 +54,23 @@ pkg_array_init_from_db(struct pkg_array *a)
assert(i == a->n_pkgs);
}
+/**
+ * Sort a package array.
+ *
+ * @param a The array to sort.
+ * @param pkg_sort The function to sort the array.
+ */
void
pkg_array_sort(struct pkg_array *a, pkg_sorter_func *pkg_sort)
{
qsort(a->pkgs, a->n_pkgs, sizeof(a->pkgs[0]), pkg_sort);
}
+/**
+ * Free a package array.
+ *
+ * @param a The array to free.
+ */
void
pkg_array_free(struct pkg_array *a)
{
diff --git a/lib/dpkg/pkg-array.h b/lib/dpkg/pkg-array.h
index 71d35b8..dad3496 100644
--- a/lib/dpkg/pkg-array.h
+++ b/lib/dpkg/pkg-array.h
@@ -30,6 +30,9 @@
DPKG_BEGIN_DECLS
+/**
+ * Holds an array of pointers to package data.
+ */
struct pkg_array {
int n_pkgs;
struct pkginfo **pkgs;
diff --git a/lib/dpkg/pkg.c b/lib/dpkg/pkg.c
index 2001786..8c8923b 100644
--- a/lib/dpkg/pkg.c
+++ b/lib/dpkg/pkg.c
@@ -28,6 +28,17 @@
#include <dpkg/dpkg-db.h>
#include <dpkg/pkg.h>
+/**
+ * Compare a package to be sorted by name.
+ *
+ * @param a A pointer of a pointer to a struct pkginfo.
+ * @param b A pointer of a pointer to a struct pkginfo.
+ *
+ * @return An integer with the result of the comparison.
+ * @retval -1 a is smaller than b.
+ * @retval 0 a is equal to b.
+ * @retval 1 a is greater than b.
+ */
int
pkg_sorter_by_name(const void *a, const void *b)
{
diff --git a/src/configure.c b/src/configure.c
index b309a31..02b96a2 100644
--- a/src/configure.c
+++ b/src/configure.c
@@ -209,7 +209,9 @@ deferred_configure_conffile(struct pkginfo *pkg, struct
conffile *conff)
varbuffree(&cdr2);
}
-/*
+/**
+ * Process the deferred configure package.
+ *
* The algorithm for deciding what to configure first is as follows:
* Loop through all packages doing a ‘try 1’ until we've been round
* and nothing has been done, then do ‘try 2’ and ‘try 3’ likewise.
@@ -233,6 +235,8 @@ deferred_configure_conffile(struct pkginfo *pkg, struct
conffile *conff)
*
* Try 4 (only if --force-depends):
* Do anyway.
+ *
+ * @param pkg The package to act on.
*/
void
deferred_configure(struct pkginfo *pkg)
@@ -345,9 +349,16 @@ deferred_configure(struct pkginfo *pkg)
post_postinst_tasks(pkg, stat_installed);
}
-/*
+/**
* Dereference a file by following all possibly used symlinks.
- * Returns 0 if everything went ok, -1 otherwise.
+ *
+ * @param[in] pkg The package to act on.
+ * @param[out] result The dereference conffile path.
+ * @param[in] in The conffile path to dereference.
+ *
+ * @return An error code for the operation.
+ * @retval 0 Everything went ok.
+ * @retval -1 Otherwise.
*/
int
conffderef(struct pkginfo *pkg, struct varbuf *result, const char *in)
@@ -437,9 +448,15 @@ conffderef(struct pkginfo *pkg, struct varbuf *result,
const char *in)
}
}
-/*
- * Generate a MD5 hash for fn and store it in hashbuf, which needs to be
+/**
+ * Generate a file contents MD5 hash.
+ *
+ * The caller is responsible for providing a buffer for the hash result
* at least MD5HASHLEN + 1 characters long.
+ *
+ * @param[in] pkg The package to act on.
+ * @param[out] hashbuf The buffer to store the generated hash.
+ * @param[in] fn The filename.
*/
static void
md5hash(struct pkginfo *pkg, char *hashbuf, const char *fn)
@@ -462,8 +479,11 @@ md5hash(struct pkginfo *pkg, char *hashbuf, const char *fn)
}
}
-/*
+/**
* Show a diff between two files.
+ *
+ * @param old The path to the old file.
+ * @param new The path to the new file.
*/
static void
showdiff(const char *old, const char *new)
@@ -503,8 +523,11 @@ showdiff(const char *old, const char *new)
}
}
-/*
+/**
* Suspend dpkg temporarily.
+ *
+ * Either create a subprocess and execute a shell or background the current
+ * process to allow the user to manually solve the conffile conflict.
*/
static void
suspend(void)
--
dpkg's main repository
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]
