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

[Jonathan Nieder <jrnieder@gmail.com>]

Sean Finney wrote:

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

There are not many of these documentation comments, but adding some
seems like a good idea, especially if these functions are to
eventually be usable by other frontends.

Will documentation processing tools choke on the string /*** used
elsewhere?  (Just curious.)

> + *
> + * 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).

Some pedantic clarifications:

	@param pkg The name of the package

	@param cfgfile Name of the conffile to be updated

	@param realold Name of a file with the configuration file's
	       previous contents, possibly modified by the
	       administrator.  Can be a symlink, in which case it will
	       be dereferenced.

	@param realnew Name of a file with the configuration file's
	       updated default contents.  If a symlink, will be
	       dereferenced.

Am I understanding correctly?

> + * @param what Hints on what action should be taken by defualt.

These contain not just hints but required information, right?

Maybe I am being too pedantic here, since most functions don’t have
documentation at all!  So feel free to ignore. :)

Thanks for the interesting read.

Regards,
Jonathan