[PATCH] Add documentation for dpkg/version.h
Hi,
Attached is a proposed patch to add doxygen documentation for the
contents of dpkg/version.h. I was not sure if you would have preferred
a bug for this or not, so here it is by mail. The resulting doxygen
documentation can be seen at [1].
As an added bonus, there is also a typo fix for doc/coding-style.txt
~Niels
[1] http://people.debian.org/~nthykier/dpkg-doxygen/group__version.html
>From 2afb5a1114602601ea0d07b1208d21bbf2784018 Mon Sep 17 00:00:00 2001
From: Niels Thykier <niels@thykier.net>
Date: Thu, 24 May 2012 13:08:51 +0200
Subject: [PATCH 1/2] Fix two typoes in doc/coding-style.txt
Signed-off-by: Niels Thykier <niels@thykier.net>
---
doc/coding-style.txt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/coding-style.txt b/doc/coding-style.txt
index dbeb2b7..06fb587 100644
--- a/doc/coding-style.txt
+++ b/doc/coding-style.txt
@@ -28,12 +28,12 @@ Code should generally strive for clarity. Monster functions should be split
into logical and small pieces.
Variable and function names should be generally descriptive, not needed
-for variables commonly used (for example and index inside a loop, etc),
+for variables commonly used (for example an index inside a loop, etc),
acronyms should only be used if they are widely known externally or
inside the project. The names should separate logical concepts within
with underscores.
-On comments use UTF-8 characters for quotes, copyrigth symbols, etc.
+On comments use UTF-8 characters for quotes, copyright symbols, etc.
On strings in code use simple or double quotes «''» «""». Not the unpaired
ones «`'». Strings marked for translation, should only be fixed if there's
--
1.7.10
>From fe2590d7a230111acb4e77d30bc5e5a65161c0a1 Mon Sep 17 00:00:00 2001
From: Niels Thykier <niels@thykier.net>
Date: Thu, 24 May 2012 13:47:10 +0200
Subject: [PATCH 2/2] Add documentation for dpkg/version.h
Signed-off-by: Niels Thykier <niels@thykier.net>
---
lib/dpkg/version.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 73 insertions(+)
diff --git a/lib/dpkg/version.h b/lib/dpkg/version.h
index ba59884..07b84c2 100644
--- a/lib/dpkg/version.h
+++ b/lib/dpkg/version.h
@@ -34,25 +34,98 @@ DPKG_BEGIN_DECLS
* @{
*/
+/**
+ * Data structure representing a Debian version string.
+ *
+ * @see http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
+ */
struct dpkg_version {
+ /**
+ * The epoch. It will be zero if no epoch is present.
+ */
unsigned int epoch;
+ /**
+ * The upstream part of the version.
+ */
const char *version;
+ /**
+ * The Debian revision part of the version.
+ */
const char *revision;
};
+/**
+ * Enum constants for the supported relation operations that can be done
+ * on Debian versions.
+ */
enum dpkg_relation {
+ /**
+ * The "none" relation, sentinel value.
+ */
dpkg_relation_none = 0,
+ /**
+ * Equality relation ("=").
+ */
dpkg_relation_eq = DPKG_BIT(0),
+ /**
+ * Less than relation ("<<").
+ */
dpkg_relation_lt = DPKG_BIT(1),
+ /**
+ * Less than or equal to relation ("<=").
+ */
dpkg_relation_le = dpkg_relation_lt | dpkg_relation_eq,
+ /**
+ * Greater than relation (">>").
+ */
dpkg_relation_gt = DPKG_BIT(2),
+ /**
+ * Greater than or equal to relation (">=").
+ */
dpkg_relation_ge = dpkg_relation_gt | dpkg_relation_eq,
};
+/**
+ * Turn the passed version into an empty version. This can be used
+ * to ensure the version is properly initialized.
+ *
+ * @param version The version to clear.
+ */
void dpkg_version_blank(struct dpkg_version *version);
+/**
+ * Test if a version is not empty.
+ *
+ * @param version The version to test.
+ * @retval true If the version is informative (i.e. not an empty version).
+ * @retval false If the version is empty.
+ */
bool dpkg_version_is_informative(const struct dpkg_version *version);
+/**
+ * Compares two Debian versions according to the rules defined in the
+ * Debian Policy Manual. This function follows the convention of
+ * comparator functions used by qsort().
+ *
+ * @param a The first version.
+ * @param b The second version.
+ * @retval 0 if a and b are equal.
+ * @retval <0 if a is smaller than b.
+ * @retval >0 if a is greater than b.
+ * @see http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version
+ */
int dpkg_version_compare(const struct dpkg_version *a,
const struct dpkg_version *b);
+/**
+ * Check if two versions have a certain relation.
+ *
+ * @param a The first version.
+ * @param rel The relation.
+ * @param b The second version.
+ * @retval true If the expression "a rel b" is true.
+ * @retval true If rel is #dpkg_relation_none
+ * @retval false Otherwise.
+ * @warning If rel is not a valid relation, this function will terminate
+ * the program.
+ */
bool dpkg_version_relate(const struct dpkg_version *a,
enum dpkg_relation rel,
const struct dpkg_version *b);
--
1.7.10
Reply to: