diff options
author | Guillem Jover <guillem@debian.org> | 2009-10-11 16:33:21 +0200 |
---|---|---|
committer | Guillem Jover <guillem@debian.org> | 2009-10-26 22:55:52 +0100 |
commit | e000e4a109b95bc43e558e2f53bc85bc63d3177d (patch) | |
tree | 8ffe7f0c6fa684e8a3facb60408d4df8ddce7a69 | |
parent | 2ba520490b52db98282a4476d23d9fd8c5798270 (diff) | |
download | dpkg-e000e4a109b95bc43e558e2f53bc85bc63d3177d.tar.gz |
Document some of the code with JavaDoc
-rw-r--r-- | lib/dpkg/pkg-array.c | 16 | ||||
-rw-r--r-- | lib/dpkg/pkg-array.h | 3 | ||||
-rw-r--r-- | lib/dpkg/pkg.c | 11 | ||||
-rw-r--r-- | src/configure.c | 37 |
4 files changed, 60 insertions, 7 deletions
diff --git a/lib/dpkg/pkg-array.c b/lib/dpkg/pkg-array.c index 5a3ad9e65..ae446a532 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 71d35b8fe..dad349694 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 200178648..8c8923b2c 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 b309a310b..02b96a231 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) |