Re: [PATCH 2/6] Add doxygen comments for promptconfaction

[Guillem Jover <guillem@debian.org>]

Hi!

Cleaned up the doxygen file I had around and infrastructure changes
needed and pushed those.

Also pushed this patch with slight changes, thanks!

On Wed, 2009-10-14 at 21:23:05 +0200, Sean Finney wrote:
> diff --git a/src/configure.c b/src/configure.c
> index 1aa8b6a..d01a856 100644
> --- a/src/configure.c
> +++ b/src/configure.c
> @@ -61,6 +61,29 @@ static int conffoptcells[2][2] = {
>  static void md5hash(struct pkginfo *pkg, char *hashbuf, const char *fn);
>  static void showdiff(const char *old, const char *new);
>  static void suspend(void);
> +
> +/** Prompt the user for how to resolve a conffile conflict
> + *

The first line should be empty, followed by the brief description,

/**
 * Brief description.
 *

> + * When encountering a conffile conflict during configuration, the user will
> + * normally be presented with a textual menu of possible actions. This
> + * behavior is modified via various --force flags and perhaps on whether
> + * or not a terminal is available to do the prompting.
> + *
> + * @param pkg The package owning the conffile
> + * @param cfgfile The conffile
> + * @param realold The location of the old conffile (dereferenced in the case
> + *        of a symlink).
> + * @param realnew The location of the new conffile (dereferenced in the case
> + *        of a symlink).
> + * @param useredited A flag to indicate whether the file has been edited
> + *        locally. Set to nonzero to indicate that the file has been modified.
> + * @param distedited A flag to indicate whether the file has been updated 
> + *        between package versions.  Set to nonzero to indicate that
> + *        the file has been updated.
> + * @param what Hints on what action should be taken by defualt.

Reworded some of the @params to try to make them more clear.

A blank line before @return.

> + * @return The action which should be taken based on user input and/or the
> + *         default actions as configured by cmdline/configuration options.
> + */

>  static enum conffopt promptconfaction(const char *pkg, const char *cfgfile,
>                                        const char *realold, const char *realnew,
>                                        int useredited, int distedited,

JavaDoc comments should go closer to the definition of the code, except
for type declarations (enums, structs, typedefs, etc), which should go
closer to the declaration, usually in the header files.

I should probably add this to the coding-style.txt.

regards,
guillem