The following commit has been merged in the master branch:
commit 7ee4f4f2ef5ca3d9fa1426ac93f78ead2280bc36
Author: Guillem Jover <[email protected]>
Date: Mon Nov 1 07:02:21 2010 +0100
Add doxygen comments to several functions
diff --git a/lib/dpkg/dir.c b/lib/dpkg/dir.c
index bcfdd61..e1770ae 100644
--- a/lib/dpkg/dir.c
+++ b/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)
{
diff --git a/lib/dpkg/file.c b/lib/dpkg/file.c
index 242edf4..424e932 100644
--- a/lib/dpkg/file.c
+++ b/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)
{
diff --git a/lib/dpkg/parse.c b/lib/dpkg/parse.c
index 4935b22..cc65601 100644
--- a/lib/dpkg/parse.c
+++ b/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
},
diff --git a/lib/dpkg/path.c b/lib/dpkg/path.c
index 7807334..c6caf15 100644
--- a/lib/dpkg/path.c
+++ b/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)
{
diff --git a/lib/dpkg/pkg-list.c b/lib/dpkg/pkg-list.c
index 88f65c9..6859468 100644
--- a/lib/dpkg/pkg-list.c
+++ b/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)
{
diff --git a/lib/dpkg/pkg-queue.c b/lib/dpkg/pkg-queue.c
index c85c965..0e1c3e1 100644
--- a/lib/dpkg/pkg-queue.c
+++ b/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)
{
diff --git a/lib/dpkg/pkg-queue.h b/lib/dpkg/pkg-queue.h
index 751dbce..af094ed 100644
--- a/lib/dpkg/pkg-queue.h
+++ b/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 }
diff --git a/lib/dpkg/string.c b/lib/dpkg/string.c
index 4e4e5f8..e3b8ed3 100644
--- a/lib/dpkg/string.c
+++ b/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)
{
--
dpkg's main repository
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]
