Add doxygen comments to several functions

lib/dpkg/dir.c

@@ -35,6 +35,12 @@
 #include <dpkg/varbuf.h>
 #include <dpkg/dir.h>
 
+/**
+ * Sync a directory to disk from a DIR structure.
+ *
+ * @param dir The directory to sync.
+ * @param path The name of the directory to sync (for error messages).
+ */
 void
 dir_sync(DIR *dir, const char *path)
 {
@@ -49,6 +55,11 @@ dir_sync(DIR *dir, const char *path)
 		ohshite(_("unable to sync directory '%s'"), path);
 }
 
+/**
+ * Sync a directory to disk from a pathname.
+ *
+ * @param path The name of the directory to sync.
+ */
 void
 dir_sync_path(const char *path)
 {
@@ -63,6 +74,11 @@ dir_sync_path(const char *path)
 	closedir(dir);
 }
 
+/**
+ * Sync to disk the parent directory of a pathname.
+ *
+ * @param path The child pathname of the directory to sync.
+ */
 void
 dir_sync_path_parent(const char *path)
 {
@@ -100,6 +116,11 @@ dir_file_sync(const char *dir, const char *filename)
 	varbuf_destroy(&path);
 }
 
+/**
+ * Sync to disk the contents and the directory specified.
+ *
+ * @param path The pathname to sync.
+ */
 void
 dir_sync_contents(const char *path)
 {

lib/dpkg/file.c

@@ -84,6 +84,9 @@ file_unlock_cleanup(int argc, void **argv)
 		ohshite(_("unable to unlock %s"), lock_desc);
 }
 
+/**
+ * Unlock a previously locked file.
+ */
 void
 file_unlock(void)
 {

lib/dpkg/parse.c

@@ -43,6 +43,9 @@
 #include <dpkg/parsedump.h>
 #include <dpkg/buffer.h>
 
+/**
+ * Fields information.
+ */
 const struct fieldinfo fieldinfos[]= {
   /* Note: Capitalization of field name strings is important. */
   { "Package",          f_name,            w_name                                     },

lib/dpkg/path.c

@@ -30,6 +30,15 @@
 #include <dpkg/varbuf.h>
 #include <dpkg/path.h>
 
+/**
+ * Trim ‘/’ and ‘/.’ from the end of a pathname.
+ *
+ * The given string will get NUL-terminatd.
+ *
+ * @param path The pathname to trim.
+ *
+ * @return The size of the trimmed pathname.
+ */
 size_t
 path_rtrim_slash_slashdot(char *path)
 {
@@ -48,6 +57,13 @@ path_rtrim_slash_slashdot(char *path)
 	return end - path + 1;
 }
 
+/**
+ * Skip ‘/’ and ‘./’ from the beginning of a pathname.
+ *
+ * @param path The pathname to skip.
+ *
+ * @return The new beginning of the pathname.
+ */
 const char *
 path_skip_slash_dotslash(const char *path)
 {

lib/dpkg/pkg-list.c

@@ -27,6 +27,14 @@
 #include <dpkg/dpkg-db.h>
 #include <dpkg/pkg-list.h>
 
+/**
+ * Create a new package list node.
+ *
+ * @param pkg The pkginfo to assign to the node.
+ * @param next The next package list node.
+ *
+ * @return The new package list node.
+ */
 struct pkg_list *
 pkg_list_new(struct pkginfo *pkg, struct pkg_list *next)
 {
@@ -39,6 +47,11 @@ pkg_list_new(struct pkginfo *pkg, struct pkg_list *next)
 	return node;
 }
 
+/**
+ * Free all nodes of a package list.
+ *
+ * @param head The head of the list to free.
+ */
 void
 pkg_list_free(struct pkg_list *head)
 {
@@ -52,6 +65,12 @@ pkg_list_free(struct pkg_list *head)
 	}
 }
 
+/**
+ * Prepend a package list node to a package list.
+ *
+ * @param head The head of the list to prepend to.
+ * @param pkg The pkginfo to prepend to the list.
+ */
 void
 pkg_list_prepend(struct pkg_list **head, struct pkginfo *pkg)
 {

lib/dpkg/pkg-queue.c

@@ -26,6 +26,11 @@
 #include <dpkg/dpkg-db.h>
 #include <dpkg/pkg-queue.h>
 
+/**
+ * Initialize a package queue.
+ *
+ * @param queue The queue to initialize.
+ */
 void
 pkg_queue_init(struct pkg_queue *queue)
 {
@@ -34,6 +39,13 @@ pkg_queue_init(struct pkg_queue *queue)
 	queue->length = 0;
 }
 
+/**
+ * Destroy a package queue.
+ *
+ * It frees the contained package list and resets the queue members.
+ *
+ * @param queue The queue to destroy.
+ */
 void
 pkg_queue_destroy(struct pkg_queue *queue)
 {
@@ -41,12 +53,27 @@ pkg_queue_destroy(struct pkg_queue *queue)
 	pkg_queue_init(queue);
 }
 
+/**
+ * Check if a package queue is empty.
+ *
+ * @param queue The queue to check.
+ *
+ * @return A boolean value.
+ */
 int
 pkg_queue_is_empty(struct pkg_queue *queue)
 {
 	return (queue->head == NULL);
 }
 
+/**
+ * Push a new node containing pkginfo to the tail of the queue.
+ *
+ * @param queue The queue to insert to.
+ * @param pkg The package to use fo the new node.
+ *
+ * @return The newly inserted pkg_list node.
+ */
 struct pkg_list *
 pkg_queue_push(struct pkg_queue *queue, struct pkginfo *pkg)
 {
@@ -66,6 +93,16 @@ pkg_queue_push(struct pkg_queue *queue, struct pkginfo *pkg)
 	return node;
 }
 
+/**
+ * Pop a node containing pkginfo from the head of the queue.
+ *
+ * This removes and frees the node from the queue, effectively reducing its
+ * size.
+ *
+ * @param queue The queue to remove from.
+ *
+ * @return The pkginfo from the removed node, or NULL if the queue was empty.
+ */
 struct pkginfo *
 pkg_queue_pop(struct pkg_queue *queue)
 {

lib/dpkg/pkg-queue.h

@@ -31,6 +31,9 @@ struct pkg_queue {
 	int length;
 };
 
+/**
+ * Initializer for a package queue.
+ */
 #define PKG_QUEUE_INIT \
 	(struct pkg_queue){ .head = NULL, .tail = NULL, .length = 0 }
 

lib/dpkg/string.c

@@ -26,6 +26,15 @@
 
 #include <dpkg/string.h>
 
+/**
+ * Escape format characters from a string.
+ *
+ * @param dst The destination string.
+ * @param src The source string.
+ * @param n The size of the destination buffer.
+ *
+ * @return The end of the destination string.
+ */
 char *
 str_escape_fmt(char *dst, const char *src, size_t n)
 {