From: Greg Hudson <ghudson@mit.edu>
Date: Sat, 12 Jan 2013 04:55:07 +0000 (-0500)
Subject: Flesh out responder context doxygen markup
X-Git-Tag: krb5-1.12-alpha1~343
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=30e2a3eaa7ba2fd11c4a26a8fef58a5591010c43;p=thirdparty%2Fkrb5.git

Flesh out responder context doxygen markup
---

diff --git a/doc/appdev/refs/types/index.rst b/doc/appdev/refs/types/index.rst
index 5efdd6c82b..0b39d5abfa 100644
--- a/doc/appdev/refs/types/index.rst
+++ b/doc/appdev/refs/types/index.rst
@@ -64,6 +64,7 @@ Public
    krb5_prompt_type.rst
    krb5_prompter_fct.rst
    krb5_pwd_data.rst
+   krb5_responder_context.rst
    krb5_responder_fn.rst
    krb5_responder_otp_challenge.rst
    krb5_responder_otp_tokeninfo.rst
diff --git a/doc/tools/doxybuilder_types.py b/doc/tools/doxybuilder_types.py
index 890dc2cc4a..4bb6e1868f 100644
--- a/doc/tools/doxybuilder_types.py
+++ b/doc/tools/doxybuilder_types.py
@@ -35,7 +35,7 @@ exclude_types = [ 'TRUE', 'FALSE', 'KRB5_ATTR_DEPRECATED',
                   'KRB5_GENERAL__', 'KRB5_KEYUSAGE_PA_REFERRAL',
                   'KRB5_OLD_CRYPTO',
                   'KRB5INT_BEGIN_DECLS', 'KRB5INT_END_DECLS',
-                  'krb5_cc_ops', 'krb5_octet_data', 'krb5_responder_context' ]
+                  'krb5_cc_ops', 'krb5_octet_data' ]
 
 class DoxyTypes(object):
     def __init__(self, xmlpath):
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 6b8b2e2fc6..4a7e5c0f1c 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -6444,6 +6444,18 @@ krb5_prompter_posix(krb5_context context, void *data, const char *name,
  */
 #define KRB5_RESPONDER_OTP_FLAGS_SEPARATE_PIN  0x0008
 
+/**
+ * A container for a set of preauthentication questions and answers
+ *
+ * A responder context is supplied by the krb5 authentication system to a @ref
+ * krb5_responder_fn callback.  It contains a list of questions and can receive
+ * answers.  Questions contained in a responder context can be listed using
+ * krb5_responder_list_questions(), retrieved using responder_get_challenge(),
+ * or answered using krb5_responder_set_answer().  The form of a question's
+ * challenge and answer depend on the question name.
+ *
+ * @version First introduced in 1.11
+ */
 typedef struct krb5_responder_context_st *krb5_responder_context;
 
 /**
@@ -6452,6 +6464,12 @@ typedef struct krb5_responder_context_st *krb5_responder_context;
  * @param [in] ctx              Library context
  * @param [in] rctx             Responder context
  *
+ * Return a pointer to a null-terminated list of question names which are
+ * present in @a rctx.  The pointer is an alias, valid only as long as the
+ * lifetime of @a rctx, and should not be modified or freed by the caller.  A
+ * question's challenge can be retrieved using krb5_responder_get_challenge()
+ * and answered using krb5_responder_set_answer().
+ *
  * @version First introduced in 1.11
  */
 const char * const * KRB5_CALLCONV
@@ -6464,6 +6482,13 @@ krb5_responder_list_questions(krb5_context ctx, krb5_responder_context rctx);
  * @param [in] rctx             Responder context
  * @param [in] question         Question name
  *
+ * Return a pointer to a C string containing the challenge for @a question
+ * within @a rctx, or NULL if the question is not present in @a rctx.  The
+ * structure of the question depends on the question name, but will always be
+ * printable UTF-8 text.  The returned pointer is an alias, valid only as long
+ * as the lifetime of @a rctx, and should not be modified or freed by the
+ * caller.
+ *
  * @version First introduced in 1.11
  */
 const char * KRB5_CALLCONV
@@ -6478,6 +6503,11 @@ krb5_responder_get_challenge(krb5_context ctx, krb5_responder_context rctx,
  * @param [in] question         Question name
  * @param [in] answer           The string to set (MUST be printable UTF-8)
  *
+ * This function supplies an answer to @a question within @a rctx.  The
+ * appropriate form of the answer depends on the question name.
+ *
+ * @retval EINVAL @a question is not present within @a rctx
+ *
  * @version First introduced in 1.11
  */
 krb5_error_code KRB5_CALLCONV