Re: [PATCH] Add documentation for dpkg/version.h
Hi!
On Thu, 2012-05-24 at 15:07:23 +0200, Niels Thykier wrote:
> 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.
For patches, either is fine.
> The resulting doxygen documentation can be seen at [1].
Oh, I thought I had pushed the doxygen docs to dpkg.alioth.debian.org
already, I'll do that once I've pushed these changes to the git repo.
> As an added bonus, there is also a typo fix for doc/coding-style.txt
Nice, I'll add some more text though to the documentation section, as
it's currently not very helpful.
> Subject: [PATCH 1/2] Fix two typoes in doc/coding-style.txt
Applied.
> Subject: [PATCH 2/2] Add documentation for dpkg/version.h
This one I've reworked a bit. Thanks!
> 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
> + */
I've referred to the deb-version(5) man page instead, so that this is
self-contained in the dpkg sources.
> struct dpkg_version {
> + /**
> + * The epoch. It will be zero if no epoch is present.
> + */
I've changed this to a single line comment, like other enum values.
And used one space after dot.
> +/**
> + * 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);
I've moved the docs for functions to the .c file, because that way
when the code changes it's easier to see if the docs need to be
updated too. And left the title line on its own and moved the
description to a new paragraph.
thanks,
guillem
Reply to: