[PATCH 2/6] Add doxygen comments for promptconfaction

[Sean Finney <seanius@debian.org>]

---
 src/configure.c |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)

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
+ *
+ * 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.
+ * @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,
-- 
1.6.4.3