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 <[email protected]> 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 <[email protected]> --- 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 <[email protected]> Date: Thu, 24 May 2012 13:47:10 +0200 Subject: [PATCH 2/2] Add documentation for dpkg/version.h Signed-off-by: Niels Thykier <[email protected]> --- 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
