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

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


--
To UNSUBSCRIBE, email to debian-dpkg-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 20120524183541.GA32551@gaara.hadrons.org">http://lists.debian.org/20120524183541.GA32551@gaara.hadrons.org

On 2012-05-24 20:35, Guillem Jover wrote:
> Hi!
>

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.
>

Okay, for documentation or minor fixes I will probably stick to mail
then.

>> 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.
>

I had forgotten that site existed.

>> 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.
>

Much appreciated, I will keep my eyes opened for it.

>> [...]
>> Subject: [PATCH 2/2] Add documentation for dpkg/version.h
>
> This one I've reworked a bit. Thanks!
>
>> [...]
>
> thanks,
> guillem
>
>

Thanks for the pointers, I will keep them in mind.

~Niels


--
To UNSUBSCRIBE, email to debian-dpkg-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4FC075CF.6020609@thykier.net">http://lists.debian.org/4FC075CF.6020609@thykier.net