Document some of the code with JavaDoc

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)
 {

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;

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)
 {

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)