Formatting and editorial pass over krb5.hin doxygen markup

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24973 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 2482 insertions, 2356 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 8aed7b68a5..76c98cd0c2 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -289,16 +289,18 @@ typedef const krb5_principal_data *krb5_const_principal;
  * Referral-specific functions.
  */
 
-/** Check for a match with KRB5_REFERRAL_REALM.
+/**
+ * Check for a match with KRB5_REFERRAL_REALM.
  *
- * @param [in] r  Realm to check
+ * @param [in] r                Realm to check
  *
- * @retval TRUE if @a r is zero-length; Otherwise - FALSE
+ * @return @c TRUE if @a r is zero-length, @c FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_is_referral_realm(const krb5_data *r);
 
-/** Return an anonymous realm data.
+/**
+ * Return an anonymous realm data.
  *
  * This function returns constant storage that must not be freed.
  *
@@ -307,7 +309,8 @@ krb5_is_referral_realm(const krb5_data *r);
 const krb5_data *KRB5_CALLCONV
 krb5_anonymous_realm(void);
 
-/** Build an anonymous principal.
+/**
+ * Build an anonymous principal.
  *
  * This function returns constant storage that must not be freed.
  *
@@ -374,13 +377,13 @@ typedef struct _krb5_keyblock {
     krb5_octet *contents;
 } krb5_keyblock;
 
-/** Opaque identifier for a key.
+/**
+ * Opaque identifier for a key.
  *
- * Use with the krb5_k APIs for better
- * performance for repeated operations with the same key usage.  Key
- * identifiers must not be used simultaneously within multiple
- * threads, as they may contain mutable internal state and are not
- * mutex-protected.
+ * Use with the krb5_k APIs for better performance for repeated operations with
+ * the same key and usage.  Key identifiers must not be used simultaneously
+ * within multiple threads, as they may contain mutable internal state and are
+ * not mutex-protected.
  */
 struct krb5_key_st;
 typedef struct krb5_key_st *krb5_key;
@@ -420,7 +423,7 @@ typedef struct _krb5_crypto_iov {
 #define ENCTYPE_DES_CBC_MD4     0x0002  /**< DES cbc mode with RSA-MD4 */
 #define ENCTYPE_DES_CBC_MD5     0x0003  /**< DES cbc mode with RSA-MD5 */
 #define ENCTYPE_DES_CBC_RAW     0x0004  /**< @deprecated DES cbc mode raw */
-#define ENCTYPE_DES3_CBC_SHA    0x0005  /**< @deprecated DES-3 cbc mode with NIST-SHA */
+#define ENCTYPE_DES3_CBC_SHA    0x0005  /**< @deprecated DES-3 cbc with SHA1 */
 #define ENCTYPE_DES3_CBC_RAW    0x0006  /**< @deprecated DES-3 cbc mode raw */
 #define ENCTYPE_DES_HMAC_SHA1   0x0008  /**< @deprecated */
 /* PKINIT */
@@ -454,19 +457,21 @@ typedef struct _krb5_crypto_iov {
 #define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
 #define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/
 
-/* The following are entropy source designations. Whenever
- * krb5_C_random_add_entropy is called, one of these source  ids is passed
- * in.  This  allows the library  to better estimate bits of
- * entropy in the sample and to keep track of what sources of entropy have
- * contributed enough entropy.  Sources marked internal MUST NOT be
- * used by applications outside the Kerberos library
+/*
+ * The following are entropy source designations. Whenever
+ * krb5_C_random_add_entropy is called, one of these source ids is passed in.
+ * This allows the library to better estimate bits of entropy in the sample and
+ * to keep track of what sources of entropy have contributed enough entropy.
+ * Sources marked internal MUST NOT be used by applications outside the
+ * Kerberos library
  */
 
 enum {
     KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/
     KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/
     KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/
-    /*This source should be used carefully; data in this category
+    /*
+     * This source should be used carefully; data in this category
      * should be from a third party trusted to give random bits
      * For example keys issued by the KDC in the application server.
      */
@@ -490,179 +495,182 @@ enum {
 #define krb5_xc(ptr,args) ((*(ptr)) args)
 #endif
 
- /** Encrypt data using a key.
+/**
+ * Encrypt data using a key.
  *
- * @param          context        Context structure
- * @param [in]     key            Enryption key
- * @param [in]     usage          Key usage (see KRB5_KEYUSAGE types)
- * @param [in,out] cipher_state   Initial vector; specify NULL if not needed
- * @param [in]     input          Data to be encrypted
- * @param [out]    output         Encrypted data
+ * @param [in]     context      Library context
+ * @param [in]     key          Encryption key
+ * @param [in]     usage        Key usage (see KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in]     input        Data to be encrypted
+ * @param [out]    output       Encrypted data
  *
- * This function encrypts the data block @a input and stores the output
- * into @a output. The actual encryption key will derive from @a key if
- * key derivation is permitted for the encryption algorithm.
- * @a cipher_state specifies the starting value for the encryption operation,
- * and is updated with the state to be passed as input to the next operation.
+ * This function encrypts the data block @a input and stores the output into @a
+ * output.  The actual encryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type.  If non-null, @a
+ * cipher_state specifies the beginning state for the encryption operation, and
+ * is updated with the state to be passed as input to the next operation.
  *
  * @note The caller must initialize @a output and allocate at least enough
  * space for the result (using krb5_c_encrypt_length() to determine the amount
- * of space needed). @a output->length will be set to the actual length of the
- * ciphertext if it was larger.
+ * of space needed).  @a output->length will be set to the actual length of the
+ * ciphertext.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_encrypt(krb5_context context, const krb5_keyblock *key,
                krb5_keyusage usage, const krb5_data *cipher_state,
                const krb5_data *input, krb5_enc_data *output);
 
-/** Decrypt data using a key.
+/**
+ * Decrypt data using a key.
  *
- * @param          context        Context structure
- * @param [in]     key            Enryption key
- * @param [in]     usage          Key usage (see KRB5_KEYUSAGE types)
- * @param [in,out] cipher_state   Initial vector; specify NULL if not needed
- * @param [in]     input          Encrypted data
- * @param [out]    ouput          Decrypted data
+ * @param [in]     context      Library context
+ * @param [in]     key          Encryption key
+ * @param [in]     usage        Key usage (see KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in]     input        Encrypted data
+ * @param [out]    output       Decrypted data
  *
- * This function decrypts the data block @a input and stores the output
- * into @a output. The actual decryption key will derive from @a key if
- * key derivation is permitted for the encryption algorithm.
- * @a cipher_state specifies the starting value for the decryption operation,
- * and is updated with the state to be passed as input to the next operation.
+ * This function decrypts the data block @a input and stores the output into @a
+ * output. The actual decryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type.  If non-null, @a
+ * cipher_state specifies the beginning state for the decryption operation, and
+ * is updated with the state to be passed as input to the next operation.
  *
  * @note The caller must initialize @a output and allocate at least enough
- * space for the result. The usual practice is to allocate an output buffer
- * as long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
- * For some enctypes, the resulting output->length may include padding bytes
- * (DES and DES3 enctypes do not have self-describing padding, so it is
- * impossible to separate the plaintext from the padding based only on the
- * ciphertext token).
+ * space for the result.  The usual practice is to allocate an output buffer as
+ * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
+ * For some enctypes, the resulting @a output->length may include padding
+ * bytes.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
-
 krb5_error_code KRB5_CALLCONV
 krb5_c_decrypt(krb5_context context, const krb5_keyblock *key,
                krb5_keyusage usage, const krb5_data *cipher_state,
                const krb5_enc_data *input, krb5_data *output);
 
-/** Return encrypted data length.
+/**
+ * Compute encrypted data length.
  *
- * @param       context               Context structure
- * @param [in]  enctype               Encryption type
- * @param [in]  inputlen              Length of the data to be encrypted
- * @param [out] length                Length of the encrypted data
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [in]  inputlen        Length of the data to be encrypted
+ * @param [out] length          Length of the encrypted data
  *
  * This function computes the length of the ciphertext produced by encrypting
- * @a inputlen bytes and returns the length of the encrypted data including
- * padding, confounder and checksum.
+ * @a inputlen bytes including padding, confounder, and checksum.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
-
 krb5_error_code KRB5_CALLCONV
 krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype,
                       size_t inputlen, size_t *length);
 
-/** Return cipher block size.
+/**
+ * Return cipher block size.
  *
- * @param       context         Context structure
- * @param [in]  enctype         Encryption algorithm
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
  * @param [out] blocksize       Block size for @a enctype
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_block_size(krb5_context context, krb5_enctype enctype,
                   size_t *blocksize);
 
-/** Return length of the specified key in bytes.
+/**
+ * Return length of the specified key in bytes.
  *
- * @param       context              Context structure
- * @param [in]  enctype              Encryption algorithm
- * @param [out] keybytes             Number of bytes required to make a key
- * @param [out] keylength            Length of final key
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [out] keybytes        Number of bytes required to make a key
+ * @param [out] keylength       Length of final key
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
                   size_t *keybytes, size_t *keylength);
 
-/** Initialize a new cipher state.
+/**
+ * Initialize a new cipher state.
  *
- * @param       context             Context structure
- * @param [in]  key                 Key
- * @param [in]  usage               Key usage (see KRB5_KEYUSAGE types)
- * @param [out] new_state           New cipher state
+ * @param [in]  context         Library context
+ * @param [in]  key             Key
+ * @param [in]  usage           Key usage (see KRB5_KEYUSAGE types)
+ * @param [out] new_state       New cipher state
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_init_state(krb5_context context, const krb5_keyblock *key,
                   krb5_keyusage usage, krb5_data *new_state);
 
-/** Free a cipher state previously allocated by krb5_c_init_state().
+/**
+ * Free a cipher state previously allocated by krb5_c_init_state().
  *
- * @param      context           Context structure
- * @param [in] key               Key
- * @param [in] state             Cipher state to be freed
+ * @param [in] context          Library context
+ * @param [in] key              Key
+ * @param [in] state            Cipher state to be freed
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_free_state(krb5_context context, const krb5_keyblock *key,
                   krb5_data *state);
 
-/** Generate enctype-specific pseudo-random bytes.
+/**
+ * Generate enctype-specific pseudo-random bytes.
  *
- * @param       context           Context structure
- * @param [in]  keyblock          Key
- * @param [in]  input             Input data
- * @param [out] output            Output data
+ * @param [in]  context         Library context
+ * @param [in]  keyblock        Key
+ * @param [in]  input           Input data
+ * @param [out] output          Output data
  *
  * This function selects a pseudo-random function based on @a keyblock and
  * computes its value over @a input, placing the result into @a output.
  * The caller must preinitialize @a output and allocate space for the
  * result, using krb5_c_prf_length() to determine the required length.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock,
            krb5_data *input, krb5_data *output);
 
-/** Get the output length of pseudo-random functions for a given encryption type.
+/**
+ * Get the output length of pseudo-random functions for an encryption type.
  *
- * @param       context           Context structure
- * @param [in]  enctype           Encryption type
- * @param [out] len               Number of bytes for @a enctype
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [out] len             Length of PRF output
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len);
 
-/**  Returns KRB-FX-CF2 in a newly allocated keyblock.
+/**
+ * Compute the KRB-FX-CF2 combination of two keys and pepper strings.
  *
- * @param       context   Context structure
- * @param [in]  k1        KDC contribution key
- * @param [in]  pepper1   String "PKINIT"
- * @param [in]  k2        Reply key
- * @param [in]  pepper2   String "KeyExchange"
- * @param [out] out       Output key
+ * @param [in]  context         Library context
+ * @param [in]  k1              KDC contribution key
+ * @param [in]  pepper1         String "PKINIT"
+ * @param [in]  k2              Reply key
+ * @param [in]  pepper2         String "KeyExchange"
+ * @param [out] out             Output key
  *
- * This function is simple in that it assumes
- * pepper1 and pepper2 are C strings with no
- * internal nulls and that the enctype of the
- * result will be the same as that of k1.  Both
- * of these assumptions are true of current
- * specs.
- * Note that @a k1 and @a k2 can be of two different enctypes.
+ * This function computes the KRB-FX-CF2 function over its inputs and places
+ * the results in a newly allocated keyblock.  This function is simple in that
+ * it assumes that @a pepper1 and @a pepper2 are C strings with no internal
+ * nulls and that the enctype of the result will be the same as that of @a k1.
+ * @a k1 and @a k2 may be of different enctypes.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_fx_cf2_simple(krb5_context context,
@@ -670,84 +678,89 @@ krb5_c_fx_cf2_simple(krb5_context context,
                      krb5_keyblock *k2, const char *pepper2,
                      krb5_keyblock **out);
 
-/** Generate an enctype-specific random encryption key.
+/**
+ * Generate an enctype-specific random encryption key.
  *
- * @param       context        Context structure
- * @param [in]  enctype        Encryption type of the generated key
- * @param [out] k5_random_key  An allocated and initialized keyblock
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type of the generated key
+ * @param [out] k5_random_key   An allocated and initialized keyblock
  *
  * Use krb5_free_keyblock_contents() to free @a k5_random_key when
  * no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_make_random_key(krb5_context context, krb5_enctype enctype,
                        krb5_keyblock *k5_random_key);
 
-/** Generate an enctype-specific key given random data.
+/**
+ * Generate an enctype-specific key from random data.
  *
- * @param       context               Context structure
- * @param [in]  enctype               Encryption type
- * @param [in]  random_data           Random input data
- * @param [out] k5_random_key         Random key
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [in]  random_data     Random input data
+ * @param [out] k5_random_key   Resulting key
  *
- * This function takes random input data @a random_data
- * and produces a valid key @a k5_random_key for a given @a enctype.
+ * This function takes random input data @a random_data and produces a valid
+ * key @a k5_random_key for a given @a enctype.
  *
- * @note  It is assumed that @a k5_random_key has already been initialized and
+ * @note It is assumed that @a k5_random_key has already been initialized and
  * @a k5_random_key->contents has been allocated with the correct length.
  *
- * @sa  krb5_c_keylengths()
+ * @sa krb5_c_keylengths()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_to_key(krb5_context context, krb5_enctype enctype,
                      krb5_data *random_data, krb5_keyblock *k5_random_key);
 
-/** Add entropy to the pseudo-random number generator.
+/**
+ * Add entropy to the pseudo-random number generator.
  *
- * @param      context               Context structure
- * @param [in] randsource            Entropy source
- * @param [in] data                  Data
+ * @param [in] context          Library context
+ * @param [in] randsource       Entropy source (see KRB5_RANDSOURCE types)
+ * @param [in] data             Data
  *
- * @note  This might cause the @c PRNG to be reseeded,
- *        although this is not guaranteed.
+ * Contribute entropy to the PRNG used by krb5 crypto operations.  This may or
+ * may not affect the output of the next crypto operation requiring random
+ * data.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_add_entropy(krb5_context context, unsigned int randsource,
                           const krb5_data *data);
 
-/** Generate pseudo-random bytes.
+/**
+ * Generate pseudo-random bytes.
  *
- * @param       context           Context structure
- * @param [out] data              Random data
+ * @param [in]  context         Library context
+ * @param [out] data            Random data
  *
- * @a data->length specifies the number of bytes to generate and
- * @a data->data points to an allocated buffer of the correct length.
+ * Fills in @a data with bytes from the PRNG used by krb5 crypto operations.
+ * The caller must preinitialize @a data and allocate the desired amount of
+ * space.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_make_octets(krb5_context context, krb5_data *data);
 
-/** Collect entropy from the OS if possible.
+/**
+ * Collect entropy from the OS if possible.
  *
- * @param [in]  context            Context structure
- * @param [in]  strong             Strongest available source of entropy
- * @param [out] success            1 if OS provides entropy, 0 otherwise
+ * @param [in]  context         Library context
+ * @param [in]  strong          Strongest available source of entropy
+ * @param [out] success         1 if OS provides entropy, 0 otherwise
  *
  * If @a strong is non-zero, this function attempts to use the strongest
- * available source of entropy.
- *
- * Setting @a strong may increase the probability of blocking and should not
- * be used for normal applications.  Good uses include seeding the PRNG for
+ * available source of entropy.  Setting this flag may cause the function to
+ * block on some operating systems.  Good uses include seeding the PRNG for
  * kadmind and realm setup.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
@@ -756,41 +769,42 @@ krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_seed(krb5_context context, krb5_data *data);
 
-/** Convert a given string to a key.
+/**
+ * Convert a string (such a password) to a key.
  *
- * @param       context                       Context structure
- * @param [in]  enctype                       Encryption type
- * @param [in]  string                        String to be converted
- * @param [in]  salt                          Salt value
- * @param [out] key                           Generated key
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [in]  string          String to be converted
+ * @param [in]  salt            Salt value
+ * @param [out] key             Generated key
  *
- * This function converts @a string to a @a key of encryption type
- * @a enctype, using the specified @a salt.
- * The newly created @a key must be released by calling
- * krb5_free_keyblock_contents() when it is no longer needed.
+ * This function converts @a string to a @a key of encryption type @a enctype,
+ * using the specified @a salt.  The newly created @a key must be released by
+ * calling krb5_free_keyblock_contents() when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_string_to_key(krb5_context context, krb5_enctype enctype,
                      const krb5_data *string, const krb5_data *salt,
                      krb5_keyblock *key);
 
-/** Convert a given string to a key with additional parameters.
- *
- * @param       context                       Context structure
- * @param [in]  enctype                       Encryption type
- * @param [in]  string                        String to be converted
- * @param [in]  salt                          Salt value
- * @param [in]  params                        Parameters
- * @param [out] key                           Generated key
- *
- * This function is similar to krb5_c_string_to_key(), but takes
- * additional parameters.
- * The newly created @a key must be released by calling
+/**
+ * Convert a string (such as a password) to a key with additional parameters.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [in]  string          String to be converted
+ * @param [in]  salt            Salt value
+ * @param [in]  params          Parameters
+ * @param [out] key             Generated key
+ *
+ * This function is similar to krb5_c_string_to_key(), but also takes
+ * parameters which may affect the algorithm in an enctype-dependent way.  The
+ * newly created @a key must be released by calling
  * krb5_free_keyblock_contents() when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_string_to_key_with_params(krb5_context context,
@@ -800,84 +814,98 @@ krb5_c_string_to_key_with_params(krb5_context context,
                                  const krb5_data *params,
                                  krb5_keyblock *key);
 
-/** Compare two encryption types.
+/**
+ * Compare two encryption types.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  e1              First encryption type
+ * @param [in]  e2              Second encryption type
+ * @param [out] similar         @c TRUE if types are similar, @c FALSE if not
  *
- * @param       context   Context structure
- * @param [in]  e1        First encryption type
- * @param [in]  e2        Second encryption type
- * @param [out] similar   @c TRUE if types are similar, @c FALSE - otherwise
+ * This function determines whether two encryption types use the same kind of
+ * keys.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
                        krb5_boolean *similar);
 
-/** Compute a checksum.
- *
- * @param       context      Context structure
- * @param [in]  cksumtype    Checksum type; If 0 - use the mandatory checksum.
- * @param [in]  key          Encryption key for a keyed checksum
- * @param [in]  usage        @a key usage
- * @param [in]  input        Input data
- * @param [out] cksum        Generated checksum
- *
- * The newly created @a cksum must be released by calling
+/**
+ * Compute a checksum.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  cksumtype       Checksum type (0 for mandatory type)
+ * @param [in]  key             Encryption key for a keyed checksum
+ * @param [in]  usage           Key usage (see KRB5_KEYUSAGE types)
+ * @param [in]  input           Input data
+ * @param [out] cksum           Generated checksum
+ *
+ * This function computes a checksum of type @a cksumtype over @a input, using
+ * @a key if the checksum type is a keyed checksum.  If @a cksumtype is 0 and
+ * @a key is non-null, the checksum type will be the mandatory-to-implement
+ * checksum type for the key's encryption type.  The actual checksum key will
+ * be derived from @a key and @a usage if key derivation is specified for the
+ * checksum type.  The newly created @a cksum must be released by calling
  * krb5_free_checksum_contents() when it is no longer needed.
  *
  * @sa krb5_c_verify_checksum()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
                      const krb5_keyblock *key, krb5_keyusage usage,
                      const krb5_data *input, krb5_checksum *cksum);
 
-/** Verify a checksum.
+/**
+ * Verify a checksum.
  *
- * @param       context      Context structure
- * @param [in]  key          Encryption key for a keyed checksum
- * @param [in]  usage        @a key usage
- * @param [in]  data         Data to be used to compute a new checksum
- *                           using @a key to compare @a cksum against
- * @param [in]  cksum        Checksum to be verified
- * @param [out] valid        Non-zero for success, zero for failure
+ * @param [in]  context         Library context
+ * @param [in]  key             Encryption key for a keyed checksum
+ * @param [in]  usage           @a key usage
+ * @param [in]  data            Data to be used to compute a new checksum
+ *                              using @a key to compare @a cksum against
+ * @param [in]  cksum           Checksum to be verified
+ * @param [out] valid           Non-zero for success, zero for failure
  *
- * This function verifies that @a cksum is a valid checksum for
- * @a data.  If the checksum type of @a cksum is a keyed checksum, @a key
- * and @a usage are used to verify the checksum.
+ * This function verifies that @a cksum is a valid checksum for @a data.  If
+ * the checksum type of @a cksum is a keyed checksum, @a key is used to verify
+ * the checksum.  The actual checksum key will be derived from @a key and @a
+ * usage if key derivation is specified for the checksum type.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_verify_checksum(krb5_context context, const krb5_keyblock *key,
                        krb5_keyusage usage, const krb5_data *data,
                        const krb5_checksum *cksum, krb5_boolean *valid);
 
-/** Return a checksum length produced by the specified checksum type.
+/**
+ * Return the length of checksums for a checksum type.
  *
- * @param       context               Context structure
- * @param [in]  cksumtype             Checksum type
- * @param [out] length                Checksum length
+ * @param [in]  context         Library context
+ * @param [in]  cksumtype       Checksum type
+ * @param [out] length          Checksum length
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype,
                        size_t *length);
 
-/** Get a list of checksum types that match a specified encryption type.
+/**
+ * Return a list of keyed checksum types usable with an encryption type.
  *
- * @param       context     Context structure
- * @param [in]  enctype     Encryption type
- * @param [out] count       Count of checksums matching the encryption type
- * @param [out] cksumtypes  Array of checksum types with encryption key
- *                          types supported by @a enctype
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [out] count           Count of allowable checksum types
+ * @param [out] cksumtypes      Array of allowable checksum types
  *
- * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer needed.
+ * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer
+ * needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
@@ -921,7 +949,6 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
 /**
  * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL:
  * it is used for hardware Pre-athentication @a and KDC referrals.
- *
  */
 #define KRB5_KEYUSAGE_PA_REFERRAL               26 /* XXX note conflict with above */
 
@@ -941,44 +968,43 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
 #define KRB5_KEYUSAGE_ENC_CHALLENGE_KDC 55
 #define KRB5_KEYUSAGE_AS_REQ 56
 
-/** Verify that a specified encryption type is a valid Kerberos encryption type.
+/**
+ * Verify that a specified encryption type is a valid Kerberos encryption type.
  *
- * @param [in] ktype           Encryption type
+ * @param [in] ktype            Encryption type
  *
- * @retval
- * 0 - invalid;  1 - valid
+ * @return @c TRUE if @a ktype is valid, @c FALSE if not
  */
 krb5_boolean KRB5_CALLCONV
 krb5_c_valid_enctype(krb5_enctype ktype);
 
-/** Verify that specified checksum type is a valid Kerberos checksum type.
- *
- * @param ctype                        Checksum type [input]
+/**
+ * Verify that specified checksum type is a valid Kerberos checksum type.
  *
- * @retval
- * 0 - invalid;  1 - valid
+ * @param [in] ctype            Checksum type
  *
+ * @return @c TRUE if @a ctype is valid, @c FALSE if not
  */
 krb5_boolean KRB5_CALLCONV
 krb5_c_valid_cksumtype(krb5_cksumtype ctype);
 
-/** Test whether a checksum type is collision-proof.
+/**
+ * Test whether a checksum type is collision-proof.
  *
- * @param [in] ctype                        Checksum type
+ * @param [in] ctype            Checksum type
  *
- * @retval
- * 0 Not collision-proof, or checksum type is not in the list; Otherwise - 1.
+ * @return @c TRUE if @a ctype is collision-proof, @c FALSE if it is not
+ * collision-proof or not a valid checksum type.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype);
 
-/** Test whether a checksum type is keyed.
+/**
+ * Test whether a checksum type is keyed.
  *
- * @param [in] ctype                    Checksum type
+ * @param [in] ctype            Checksum type
  *
- * @retval
- * 0 Checksum does not use derived keys, or checksum type is not in the list;
- * Otherwise - 1.
+ * @return @c TRUE if @a ctype is a keyed checksum type, @c FALSE otherwise.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_c_is_keyed_cksum(krb5_cksumtype ctype);
@@ -1030,9 +1056,7 @@ krb5_error_code KRB5_CALLCONV
 krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data,
                   krb5_key *out);
 
-/**
- * Keys are logically immutable and can be "copied" by reference count.
- */
+/** Increment the reference count on a key. */
 void KRB5_CALLCONV
 krb5_k_reference_key(krb5_context context, krb5_key key);
 
@@ -1040,12 +1064,12 @@ krb5_k_reference_key(krb5_context context, krb5_key key);
 void KRB5_CALLCONV
 krb5_k_free_key(krb5_context context, krb5_key key);
 
-/** Retrieve a copy of the keyblock from a krb5_key structure.  */
+/** Retrieve a copy of the keyblock from a krb5_key structure. */
 krb5_error_code KRB5_CALLCONV
 krb5_k_key_keyblock(krb5_context context, krb5_key key,
                     krb5_keyblock **key_data);
 
-/** Retrieve the enctype of a krb5_key structure.  */
+/** Retrieve the enctype of a krb5_key structure. */
 krb5_enctype KRB5_CALLCONV
 krb5_k_key_enctype(krb5_context context, krb5_key key);
 
@@ -1236,7 +1260,8 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
 #define AP_OPTS_ETYPE_NEGOTIATION  0x00000002
 #define AP_OPTS_USE_SUBKEY         0x00000001 /**< Generate a subsession key
                                                    from the current session key
-                                                   obtained from the credentials */
+                                                   obtained from the
+                                                   credentials */
 /* #define      AP_OPTS_RESERVED        0x10000000 */
 /* #define      AP_OPTS_RESERVED        0x08000000 */
 /* #define      AP_OPTS_RESERVED        0x04000000 */
@@ -1332,16 +1357,16 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
 
 /* Message types */
 
-#define KRB5_AS_REQ     ((krb5_msgtype)10) /**< Req for initial authentication */
-#define KRB5_AS_REP     ((krb5_msgtype)11) /**< Response to KRB_AS_REQ request */
-#define KRB5_TGS_REQ    ((krb5_msgtype)12) /**< TGS request to server */
-#define KRB5_TGS_REP    ((krb5_msgtype)13) /**< Response to KRB_TGS_REQ req */
-#define KRB5_AP_REQ     ((krb5_msgtype)14) /**< application request to server */
-#define KRB5_AP_REP     ((krb5_msgtype)15) /**< Response to KRB_AP_REQ_MUTUAL */
-#define KRB5_SAFE       ((krb5_msgtype)20) /**< Safe application message */
-#define KRB5_PRIV       ((krb5_msgtype)21) /**< Private application message */
-#define KRB5_CRED       ((krb5_msgtype)22) /**< Credential forwarding message */
-#define KRB5_ERROR      ((krb5_msgtype)30) /**< Error response */
+#define KRB5_AS_REQ   ((krb5_msgtype)10) /**< Initial authentication request */
+#define KRB5_AS_REP   ((krb5_msgtype)11) /**< Response to AS request */
+#define KRB5_TGS_REQ  ((krb5_msgtype)12) /**< Ticket granting server request */
+#define KRB5_TGS_REP  ((krb5_msgtype)13) /**< Response to TGS request */
+#define KRB5_AP_REQ   ((krb5_msgtype)14) /**< Auth req to application server */
+#define KRB5_AP_REP   ((krb5_msgtype)15) /**< Response to mutual AP request */
+#define KRB5_SAFE     ((krb5_msgtype)20) /**< Safe application message */
+#define KRB5_PRIV     ((krb5_msgtype)21) /**< Private application message */
+#define KRB5_CRED     ((krb5_msgtype)22) /**< Cred forwarding message */
+#define KRB5_ERROR    ((krb5_msgtype)30) /**< Error response */
 
 /* LastReq types */
 #define KRB5_LRQ_NONE                   0
@@ -1481,8 +1506,8 @@ typedef struct _krb5_enc_tkt_part {
 /**
  * Ticket structure.
  *
- * Ticket structure that holds the C representation of the ticket protocol
- * message and a pointer to the representation of @c _krb5_enc_tkt_part.
+ * The C representation of the ticket message, with a pointer to the
+ * C representation of the encrypted part.
  */
 typedef struct _krb5_ticket {
     krb5_magic magic;
@@ -1496,7 +1521,7 @@ typedef struct _krb5_ticket {
 /**
  * Ticket authenticator.
  *
- * Ticket authenticator: the @c c representation of @c AP-REQ message with decrypted authenticator.
+ * The C representation of an unencrypted authenticator.
  */
 typedef struct _krb5_authenticator {
     krb5_magic magic;
@@ -1506,7 +1531,7 @@ typedef struct _krb5_authenticator {
     krb5_timestamp ctime;               /**< client sec portion */
     krb5_keyblock *subkey;              /**< true session key, optional */
     krb5_ui_4 seq_number;               /**< sequence #, optional */
-    krb5_authdata **authorization_data; /**< New add by Ari, auth data */
+    krb5_authdata **authorization_data; /**< authoriazation data */
 } krb5_authenticator;
 
 /*
@@ -1540,130 +1565,131 @@ typedef struct _krb5_creds {
 /** Last request entry */
 typedef struct _krb5_last_req_entry {
     krb5_magic magic;
-    krb5_int32 lr_type;   /**< LR type */
-    krb5_timestamp value;  /**< Timestamp */
+    krb5_int32 lr_type;         /**< LR type */
+    krb5_timestamp value;       /**< Timestamp */
 } krb5_last_req_entry;
 
 /** Pre-authentication data */
 typedef struct _krb5_pa_data {
     krb5_magic magic;
-    krb5_preauthtype  pa_type; /**< Preauthentication data type */
-    unsigned int length;       /**< Length of data   */
-    krb5_octet *contents;       /**< Data   */
+    krb5_preauthtype pa_type;   /**< Preauthentication data type */
+    unsigned int length;        /**< Length of data */
+    krb5_octet *contents;       /**< Data */
 } krb5_pa_data;
 
-/** Typed data.
- *
- * The FAST error handling logic currently assumes that this structure and
- * krb5_pa_data * can be safely cast to each other if this structure changes,
- * that code needs to be updated to copy.
+/*
+ * The FAST error handling logic currently assumes that pointers to this
+ * structure and krb5_pa_data can be safely cast to each other.  If this
+ * structure changes, that code needs to be updated to copy.
  */
+/** Typed data */
 typedef struct _krb5_typed_data {
     krb5_magic magic;
-    krb5_int32  type;
+    krb5_int32 type;
     unsigned int length;
     krb5_octet *data;
 } krb5_typed_data;
 
-/** Representation of KDC-REQ protocol message. */
+/** C representation of KDC-REQ protocol message, including KDC-REQ-BODY */
 typedef struct _krb5_kdc_req {
     krb5_magic magic;
-    krb5_msgtype msg_type;              /**< krb5_kdc_req AS_REQ or TGS_REQ? */
-    krb5_pa_data **padata;              /**< krb5_kdc_req e.g. encoded AP_REQ */
+    krb5_msgtype msg_type;      /**< KRB5_AS_REQ or KRB5_TGS_REQ */
+    krb5_pa_data **padata;      /**< Preauthentication data */
     /* real body */
-    krb5_flags kdc_options;             /**< requested options */
-    krb5_principal client;              /**< includes realm; optional */
-    krb5_principal server;              /**< includes realm (only used if no client) */
-    krb5_timestamp from;                /**< requested starttime */
-    krb5_timestamp till;                /**< requested endtime */
-    krb5_timestamp rtime;               /**< (optional) requested renew_till */
-    krb5_int32 nonce;                   /**< nonce to match request/response */
-    int nktypes;                        /**< # of ktypes, must be positive */
-    krb5_enctype *ktype;                /**< requested enctype(s) */
-    krb5_address **addresses;           /**< requested addresses, optional */
-    krb5_enc_data authorization_data;   /**< encrypted auth data; OPTIONAL */
-    krb5_authdata **unenc_authdata;     /**< unencrypted auth data, if available */
-    krb5_ticket **second_ticket;/**< second ticket array; OPTIONAL */
-    /** the following field is added in March 2009; it is a hack so
-     * that FAST state can be carried to pre-authentication plugins.
-     * A new plugin interface may be a better long-term approach.  It
-     * is believed to be safe to extend this structure because it is
-     * not found in any public APIs.
+    krb5_flags kdc_options;     /**< Requested options */
+    krb5_principal client;      /**< Client principal and realm */
+    krb5_principal server;      /**< Server principal and realm */
+    krb5_timestamp from;        /**< Requested start time */
+    krb5_timestamp till;        /**< Requested end time */
+    krb5_timestamp rtime;       /**< Requested renewable end time */
+    krb5_int32 nonce;           /**< Nonce to match request andresponse */
+    int nktypes;                /**< Number of enctypes */
+    krb5_enctype *ktype;        /**< Requested enctypes */
+    krb5_address **addresses;   /**< Requested addresses (optional) */
+    krb5_enc_data authorization_data;  /**< Encrypted authz data (optional) */
+    krb5_authdata **unenc_authdata;    /**< Unencrypted authz data */
+    krb5_ticket **second_ticket;       /**< Second ticket array (optional) */
+    /*
+     * The following field is added in March 2009; it is a hack so that FAST
+     * state can be carried to pre-authentication plugins.  A new plugin
+     * interface may be a better long-term approach.  It is believed to be safe
+     * to extend this structure because it is not found in any public APIs.
      */
-    void * kdc_state;
+    void *kdc_state;
 } krb5_kdc_req;
 
-/** Representation of @c EncKDCRepPart protocol message.
+/**
+ * C representation of @c EncKDCRepPart protocol message.
  *
  * This is the cleartext message that is encrypted and inserted in @c KDC-REP.
  */
-
 typedef struct _krb5_enc_kdc_rep_part {
     krb5_magic magic;
     /* encrypted part: */
-    krb5_msgtype msg_type;              /**< krb5 message type */
-    krb5_keyblock *session;             /**< session key */
-    krb5_last_req_entry **last_req;     /**< array of ptrs to entries */
-    krb5_int32 nonce;                   /**< nonce from request */
-    krb5_timestamp key_exp;             /**< expiration date */
-    krb5_flags flags;                   /**< ticket flags */
-    krb5_ticket_times times;            /**< lifetime info */
-    krb5_principal server;              /**< server's principal identifier */
-    krb5_address **caddrs;              /**< array of ptrs to addresses, optional */
-    krb5_pa_data **enc_padata;          /**< Windows 2000 compat */
+    krb5_msgtype msg_type;           /**< krb5 message type */
+    krb5_keyblock *session;          /**< Session key */
+    krb5_last_req_entry **last_req;  /**< Array of pointers to entries */
+    krb5_int32 nonce;                /**< Nonce from request */
+    krb5_timestamp key_exp;          /**< Expiration date */
+    krb5_flags flags;                /**< Ticket flags */
+    krb5_ticket_times times;         /**< Lifetime info */
+    krb5_principal server;           /**< Server's principal identifier */
+    krb5_address **caddrs;           /**< Array of ptrs to addrs, optional */
+    krb5_pa_data **enc_padata;       /**< Encrypted preauthentication data */
 } krb5_enc_kdc_rep_part;
 
-/** Representation of  the @c KDC-REP protocol message. */
+/** Representation of the @c KDC-REP protocol message. */
 typedef struct _krb5_kdc_rep {
     krb5_magic magic;
     /* cleartext part: */
-    krb5_msgtype msg_type;              /**< AS_REP or KDC_REP? */
-    krb5_pa_data **padata;              /**< preauthentication data from KDC */
-    krb5_principal client;              /**< client's principal identifier */
-    krb5_ticket *ticket;                /**< ticket */
-    krb5_enc_data enc_part;             /**< encryption type, kvno, encrypted encoding */
-    krb5_enc_kdc_rep_part *enc_part2;   /**< unencrypted version, if available */
+    krb5_msgtype msg_type;            /**< KRB5_AS_REP or KRB5_KDC_REP */
+    krb5_pa_data **padata;            /**< Preauthentication data from KDC */
+    krb5_principal client;            /**< Client principal and realm */
+    krb5_ticket *ticket;              /**< Ticket */
+    krb5_enc_data enc_part;           /**< Encrypted part of reply */
+    krb5_enc_kdc_rep_part *enc_part2; /**< Unencrypted version, if available */
 } krb5_kdc_rep;
 
 /** Error message structure */
 typedef struct _krb5_error {
     krb5_magic magic;
     /* some of these may be meaningless in certain contexts */
-    krb5_timestamp ctime;               /**< client sec portion; optional */
-    krb5_int32 cusec;                   /**< client usec portion; optional */
-    krb5_int32 susec;                   /**< server usec portion */
-    krb5_timestamp stime;               /**< server sec portion */
-    krb5_ui_4 error;                    /**< error code (protocol error #'s) */
-    krb5_principal client;              /**< client's principal identifier; optional */
-    krb5_principal server;              /**< server's principal identifier */
-    krb5_data text;                     /**< descriptive text */
-    krb5_data e_data;                   /**< additional error-describing data */
+    krb5_timestamp ctime;       /**< Client sec portion; optional */
+    krb5_int32 cusec;           /**< Client usec portion; optional */
+    krb5_int32 susec;           /**< Server usec portion */
+    krb5_timestamp stime;       /**< Server sec portion */
+    krb5_ui_4 error;            /**< Error code (protocol error #'s) */
+    krb5_principal client;      /**< Client principal and realm */
+    krb5_principal server;      /**< Server principal and realm */
+    krb5_data text;             /**< Descriptive text */
+    krb5_data e_data;           /**< Additional error-describing data */
 } krb5_error;
 
 /** Authentication header. */
 typedef struct _krb5_ap_req {
     krb5_magic magic;
-    krb5_flags ap_options;              /**< requested options */
-    krb5_ticket *ticket;                /**< ticket */
-    krb5_enc_data authenticator;        /**< authenticator (already encrypted) */
+    krb5_flags ap_options;        /**< Requested options */
+    krb5_ticket *ticket;          /**< Ticket */
+    krb5_enc_data authenticator;  /**< Encrypted authenticator */
 } krb5_ap_req;
 
-/** C representaton of AP-REP message.
+/**
+ * C representaton of AP-REP message.
  *
  * The server's response to a client's request for mutual authentication.
  */
 typedef struct _krb5_ap_rep {
     krb5_magic magic;
-    krb5_enc_data enc_part;             /**< Ciphertext of ApRepEncPart */
+    krb5_enc_data enc_part;     /**< Ciphertext of ApRepEncPart */
 } krb5_ap_rep;
 
 /** Cleartext that is encrypted and put into @c _krb5_ap_rep.  */
 typedef struct _krb5_ap_rep_enc_part {
     krb5_magic magic;
-    krb5_timestamp ctime;               /**< client time, seconds portion */
-    krb5_int32 cusec;                   /**< client time, microseconds portion */
-    krb5_keyblock *subkey;              /**< true session key, optional */
-    krb5_ui_4 seq_number;               /**< sequence #, optional */
+    krb5_timestamp ctime;       /**< Client time, seconds portion */
+    krb5_int32 cusec;           /**< Client time, microseconds portion */
+    krb5_keyblock *subkey;      /**< Subkey (optional) */
+    krb5_ui_4 seq_number;       /**< Sequence number */
 } krb5_ap_rep_enc_part;
 
 /* Unused */
@@ -1671,38 +1697,38 @@ typedef struct _krb5_response {
     krb5_magic magic;
     krb5_octet message_type;
     krb5_data response;
-    krb5_int32 expected_nonce;  /**< The expected nonce for KDC_REP messages */
-    krb5_timestamp request_time;   /**< When we made the request */
+    krb5_int32 expected_nonce;
+    krb5_timestamp request_time;
 } krb5_response;
 
 /** Credentials information inserted into @c EncKrbCredPart. */
 typedef struct _krb5_cred_info {
     krb5_magic magic;
-    krb5_keyblock *session;             /**< session key used to encrypt ticket */
-    krb5_principal client;              /**< client name/realm, optional */
-    krb5_principal server;              /**< server name/realm, optional */
-    krb5_flags flags;                   /**< ticket flags, optional */
-    krb5_ticket_times times;            /**< auth, start, end, renew_till, optional */
-    krb5_address **caddrs;              /**< array of ptrs to addresses */
+    krb5_keyblock *session;     /**< Session key used to encrypt ticket */
+    krb5_principal client;      /**< Client principal and realm */
+    krb5_principal server;      /**< Server principal and realm */
+    krb5_flags flags;           /**< Ticket flags */
+    krb5_ticket_times times;    /**< Auth, start, end, renew_till */
+    krb5_address **caddrs;      /**< Array of pointers to addrs (optional) */
 } krb5_cred_info;
 
 /** Cleartext credentials information.  */
 typedef struct _krb5_cred_enc_part {
     krb5_magic magic;
-    krb5_int32 nonce;                   /**< nonce, optional */
-    krb5_timestamp timestamp;           /**< client time */
-    krb5_int32 usec;                    /**< microsecond portion of time */
-    krb5_address *s_address;    /**< sender address, optional */
-    krb5_address *r_address;    /**< recipient address, optional */
+    krb5_int32 nonce;           /**< Nonce (optional) */
+    krb5_timestamp timestamp;   /**< Generation time, seconds portion */
+    krb5_int32 usec;            /**< Generation time, microseconds portion */
+    krb5_address *s_address;    /**< Sender address (optional) */
+    krb5_address *r_address;    /**< Recipient address (optional) */
     krb5_cred_info **ticket_info;
 } krb5_cred_enc_part;
 
 /** Credentials data structure.*/
 typedef struct _krb5_cred {
     krb5_magic magic;
-    krb5_ticket **tickets;              /**< tickets */
-    krb5_enc_data enc_part;             /**< encrypted part */
-    krb5_cred_enc_part *enc_part2;      /**< unencrypted version, if available*/
+    krb5_ticket **tickets;          /**< Tickets */
+    krb5_enc_data enc_part;         /**< Encrypted part */
+    krb5_cred_enc_part *enc_part2;  /**< Unencrypted version, if available */
 } krb5_cred;
 
 /*
@@ -1759,22 +1785,28 @@ typedef struct _krb5_pa_pac_req {
 #define KRB5_AUTH_CONTEXT_PERMIT_ALL    0x00000010
 #define KRB5_AUTH_CONTEXT_USE_SUBKEY    0x00000020
 
-/** Replay data.
+/**
+ * Replay data.
  *
- * Sequence number and timestamp information output by krb5_read_priv() and
- * krb5_read_safe().
+ * Sequence number and timestamp information output by krb5_rd_priv() and
+ * krb5_rd_safe().
  */
 typedef struct krb5_replay_data {
-    krb5_timestamp      timestamp;   /**< Timestamp, seconds portion */
-    krb5_int32          usec;        /**< Timestamp, microseconds portion */
-    krb5_ui_4           seq;         /**< Sequence number  */
+    krb5_timestamp      timestamp;  /**< Timestamp, seconds portion */
+    krb5_int32          usec;       /**< Timestamp, microseconds portion */
+    krb5_ui_4           seq;        /**< Sequence number  */
 } krb5_replay_data;
 
-/* flags for krb5_auth_con_genaddrs() */
-#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR       0x00000001 /**< Generate the local network address  */
-#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR      0x00000002 /**< Generate the remote network address.  */
-#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR  0x00000004 /**< Generate the local network address and the local port.  */
-#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008 /**< Generate the remote network address and the remote port  */
+/* Flags for krb5_auth_con_genaddrs(). */
+
+/** Generate the local network address. */
+#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR       0x00000001
+/** Generate the remote network address.  */
+#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR      0x00000002
+/** Generate the local network address and the local port. */
+#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR  0x00000004
+/** Generate the remote network address and the remote port. */
+#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008
 
 /* type of function used as a callback to generate checksum data for
  * mk_req */
@@ -1803,34 +1835,43 @@ typedef struct _krb5_cc_ops krb5_cc_ops;
 struct _krb5_cccol_cursor;
 typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;
 
-/* for retrieve_cred */
-#define KRB5_TC_MATCH_TIMES        0x00000001 /**< The requested lifetime must be
-                                                   at least as great as that specified */
-#define KRB5_TC_MATCH_IS_SKEY      0x00000002 /**< The is_skey field must match exactly */
-#define KRB5_TC_MATCH_FLAGS        0x00000004 /**< All the flags set in the match credentials
-                                                   must be set in the cache credentials */
-#define KRB5_TC_MATCH_TIMES_EXACT  0x00000008 /**< All the time fields must match exactly */
-#define KRB5_TC_MATCH_FLAGS_EXACT  0x00000010 /**< All the flags must match exactly */
-#define KRB5_TC_MATCH_AUTHDATA     0x00000020 /**< The authorization data must match */
-#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040 /**< Only the name portion
-                                                   of the principal name must match */
-#define KRB5_TC_MATCH_2ND_TKT      0x00000080 /**< The second ticket must match */
-#define KRB5_TC_MATCH_KTYPE        0x00000100 /**< The encryption key type must match */
-#define KRB5_TC_SUPPORTED_KTYPES   0x00000200 /**< The supported key types must match */
-
-/* for set_flags and other functions */
-#define KRB5_TC_OPENCLOSE          0x00000001 /**< Open and close the cache each time a
-                                                   credentials cache routine is called */
+/* Flags for krb5_cc_retrieve_cred. */
+/** The requested lifetime must be at least as great as the time specified. */
+#define KRB5_TC_MATCH_TIMES        0x00000001
+/** The is_skey field must match exactly. */
+#define KRB5_TC_MATCH_IS_SKEY      0x00000002
+/** All the flags set in the match credentials must be set. */
+#define KRB5_TC_MATCH_FLAGS        0x00000004
+/** All the time fields must match exactly. */
+#define KRB5_TC_MATCH_TIMES_EXACT  0x00000008
+/** All the flags must match exactly. */
+#define KRB5_TC_MATCH_FLAGS_EXACT  0x00000010
+/** The authorization data must match. */
+#define KRB5_TC_MATCH_AUTHDATA     0x00000020
+/** Only the name portion of the principal name must match. */
+#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040
+/** The second ticket must match. */
+#define KRB5_TC_MATCH_2ND_TKT      0x00000080
+/** The encryption key type must match. */
+#define KRB5_TC_MATCH_KTYPE        0x00000100
+/** The supported key types must match. */
+#define KRB5_TC_SUPPORTED_KTYPES   0x00000200
+
+/* Flags for krb5_cc_set_flags and similar. */
+/** Open and close the file for each cache operation. */
+#define KRB5_TC_OPENCLOSE          0x00000001
 #define KRB5_TC_NOTICKET           0x00000002
 
-/** Retrieve the name but not type of a credential cache.
+/**
+ * Retrieve the name but not type of a credential cache.
  *
- * @param [in] context          Context structure
- * @param [in] cache            Credentials cache handle
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
  *
- * @warning Returns the name of the credential cache as an alias that
- * should not be freed or modified by the caller.  This name does not
- * include the type portion, so cannot be used as input to krb5_cc_resolve().
+ * @warning Returns the name of the credential cache.  The result is an alias
+ * into @a cache and should not be freed or modified by the caller.  This name
+ * does not include the cache type, so should not be used as input to
+ * krb5_cc_resolve().
  *
  * @return
  * On success - the name of the credential cache.
@@ -1839,33 +1880,19 @@ const char * KRB5_CALLCONV
 krb5_cc_get_name(krb5_context context, krb5_ccache cache);
 
 #if KRB5_DEPRECATED
-/** Generate a new handle for a specified (unopened) credentials cache.
- *
- * @param [in]  context           Context structure
- * @param [in,out] cache          Credentials cache handle
- *
- * @deprecated Replaced by krb5_cc_new_unique()
- *
- * This function generate a new credential chache whose name is guaranteed to be unique.
- *
- * @note In the case the credential file, the cache stays unopen, but the new filename is reserved.
- *
- * @retval 0  Success; Otherwise - Kerberos error codes
- */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
 #endif /* KRB5_DEPRECATED */
 
-/** Initialize credentials cache.
- *
- * @param [in] context       Context structure
- * @param [in] cache         Credentials cache handle
- * @param [in] principal     Default principal name for the credentials cache
+/**
+ * Initialize a credential cache.
  *
- * Destroy an existing credentials cache and create a new credentials cache
- * by the same name, as specifed by @a cache for specified @a principal.
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
+ * @param [in] principal        Default principal name
  *
- * @note This function also modifies the specified credentials cache.
+ * Destroy any existing contents of @a cache and initialize it for the default
+ * principal @a principal.
  *
  * @retval
  *  0  Success
@@ -1876,17 +1903,14 @@ krb5_error_code KRB5_CALLCONV
 krb5_cc_initialize(krb5_context context, krb5_ccache cache,
                    krb5_principal principal);
 
-/** Destroy a credentials cache.
- *
- * @param [in] context          Context structure
- * @param [in] cache            Credentials cache handle
+/**
+ * Destroy a credential cache.
  *
- * This function closes and deletes @a cache and releases any other resources
- * acquired during use of the credentials cache.
- * @a cache must identify a valid credentials cache.
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
  *
- * @note After completion, @a cache may not be used. It may be reinitialized
- * with krb5_cc_resolve() or krb5_cc_gen_new().
+ * This function destroys any existing contents of @a cache and closes the
+ * handle to it.
  *
  * @retval
  * 0  Success
@@ -1896,14 +1920,14 @@ krb5_cc_initialize(krb5_context context, krb5_ccache cache,
 krb5_error_code KRB5_CALLCONV
 krb5_cc_destroy(krb5_context context, krb5_ccache cache);
 
-/** Close a credentials cache and invalidate its handle.
- *
- * @param [in] context                Context structure
- * @param [in] cache                  Credentials cache handle
+/**
+ * Close a credential cache handle.
  *
- * @a cache may be reinitialized with krb5_cc_resolve() or krb5_cc_gen_new().
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
  *
- * @sa KRB5_TC_OPENCLOSE flag
+ * This function closes a credential cache handle @a cache without affecting
+ * the contents of the cache.
  *
  * @retval
  * 0  Success
@@ -1913,69 +1937,72 @@ krb5_cc_destroy(krb5_context context, krb5_ccache cache);
 krb5_error_code KRB5_CALLCONV
 krb5_cc_close(krb5_context context, krb5_ccache cache);
 
-/** Store credentials in a specified credentials cache.
+/**
+ * Store credentials in a credential cache.
  *
- * @param [in]     context            Context structure
- * @param [in,out] cache              Credentials cache handle
- * @param [in]     creds              Credentials to be stored in cache
+ * @param [in]     context      Library context
+ * @param [in,out] cache        Credential cache handle
+ * @param [in]     creds        Credentials to be stored in cache
  *
- * This function stores @a creds into @a cache.
- * If @a creds->server and the server in the decoded ticket @a creds->ticket
- * differ, both principals will be stored.
+ * This function stores @a creds into @a cache.  If @a creds->server and the
+ * server in the decoded ticket @a creds->ticket differ, the credentials will
+ * be stored under both server principal names.
  *
  * @retval
  *  0  Success
- * @return Permission errors; Storage failure errors; Kerberos error codes
+ * @return Permission errors; storage failure errors; Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_store_cred(krb5_context context, krb5_ccache cache, krb5_creds *creds);
 
-/** Retrieve a specified credentials from a credentials cache.
+/**
+ * Retrieve a specified credentials from a credential cache.
  *
- * @param [in]  context  Context structure
- * @param [in]  cache    Credentials cache handle
- * @param [in]  flags    Flags bit mask
- * @param [in]  mcreds   Credentials to match
- * @param [out] creds    Credentials that match the requested value
+ * @param [in]  context         Library context
+ * @param [in]  cache           Credential cache handle
+ * @param [in]  flags           Flags bit mask
+ * @param [in]  mcreds          Credentials to match
+ * @param [out] creds           Credentials matching the requested value
  *
- * This function searches a credentials cache for credentials matching @a mcreds
+ * This function searches a credential cache for credentials matching @a mcreds
  * and returns it if found.
  *
  * Valid values for @a flags are:
  *
- * @li @c KRB5_TC_MATCH_TIMES        The requested lifetime must be
- *                                   at least as great as that specified.
+ * @li @c KRB5_TC_MATCH_TIMES        The requested lifetime must be at least as
+ *                                   great as in @a mcreds .
  * @li @c KRB5_TC_MATCH_IS_SKEY      The @a is_skey field much match exactly.
- * @li @c KRB5_TC_MATCH_FLAGS        The flags in @a mcreds and @a creds must match
+ * @li @c KRB5_TC_MATCH_FLAGS        Flags set in @a mcreds must be set.
  * @li @c KRB5_TC_MATCH_TIMES_EXACT  The requested lifetime must match exactly.
- * @li @c KRB5_TC_MATCH_FLAGS_EXACT  Flags in @a mcreds and @a creds must match exactly.
+ * @li @c KRB5_TC_MATCH_FLAGS_EXACT  Flags must match exactly.
  * @li @c KRB5_TC_MATCH_AUTHDATA     The authorization data must match.
- * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must
- *                                   match. The realm field can be different.
- *                                   If this flag is not set, the entire principal
- *                                   name must match.
+ * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal
+ *                                   name must match, not the realm.
  * @li @c KRB5_TC_MATCH_2ND_TKT      The second tickets must match.
  * @li @c KRB5_TC_MATCH_KTYPE        The encryption key types must match.
- * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have any supported
- *                                       encryption type and return the one with the encryption
+ * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have
+ *                                       any supported encryption type and
+ *                                       return the one with the encryption
  *                                       type listed earliest.
  *
  * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_retrieve_cred(krb5_context context, krb5_ccache cache,
                       krb5_flags flags, krb5_creds *mcreds,
                       krb5_creds *creds);
 
-/** Get the primary principal of a credentials cache.
+/**
+ * Get the default principal of a credential cache.
  *
- * @param [in]  context            Context structure
- * @param [in]  cache              Credentials cache handle
- * @param [out] principal          Primary principal
+ * @param [in]  context         Library context
+ * @param [in]  cache           Credential cache handle
+ * @param [out] principal       Primary principal
  *
- * @note The primary principal is set by calling krb5_cc_initialize().
+ * Returns the default client principal of a credential cache as set by
+ * krb5_cc_initialize().
  *
  * Use krb5_free_principal() to free @a principal when it is no longer needed.
  *
@@ -1988,52 +2015,56 @@ krb5_error_code KRB5_CALLCONV
 krb5_cc_get_principal(krb5_context context, krb5_ccache cache,
                       krb5_principal *principal);
 
-/** Prepare to sequentially read every credential in a credentials cache.
+/**
+ * Prepare to sequentially read every credential in a credential cache.
  *
- * @param [in]  context           Context structure
- * @param [in]  cache             Credentials cache handle
- * @param [out] cursor            Cursor
+ * @param [in]  context         Library context
+ * @param [in]  cache           Credential cache handle
+ * @param [out] cursor          Cursor
  *
- * krb5_cc_end_seq_get() must be called to complete the retreive operation.
+ * krb5_cc_end_seq_get() must be called to complete the retrieve operation.
  *
- * @note If @a cache was modified between the time of the call to this function
+ * @note If @a cache is modified between the time of the call to this function
  * and the time of the final krb5_cc_end_seq_get(), the results are undefined.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_start_seq_get(krb5_context context, krb5_ccache cache,
                       krb5_cc_cursor *cursor);
 
-/** Retrieve the next entry from the credentials cache.
+/**
+ * Retrieve the next entry from the credential cache.
  *
- * @param [in]     context           Context structure
- * @param [in]     cache             Credentials cache handle
- * @param [in,out] cursor            Cursor
- * @param [out]    creds             Credentials cache entry corresponding to the cursor
+ * @param [in]     context      Library context
+ * @param [in]     cache        Credential cache handle
+ * @param [in,out] cursor       Cursor
+ * @param [out]    creds        Next credential cache entry
  *
- * @note The cursor value is updated upon successful completion of this function.
- * Subsequent calls to krb5_cc_next_cred() use the updated value.
+ * This function fills in @a creds with the next entry in @a cache and advances
+ * @a cursor.
  *
  * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
  *
  * @sa krb5_cc_start_seq_get(), krb5_end_seq_get()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_next_cred(krb5_context context, krb5_ccache cache,
                   krb5_cc_cursor *cursor, krb5_creds *creds);
 
-/** Finish a series of sequential processing credentials cache entries.
+/**
+ * Finish a series of sequential processing credential cache entries.
  *
- * @param [in]     context           Context structure
- * @param [in]     cache             Credentials cache handle
- * @param [in,out] cursor            Cursor that was created by krb5_cc_start_seq_get()
+ * @param [in]     context      Library context
+ * @param [in]     cache        Credential cache handle
+ * @param [in,out] cursor       Cursor
  *
- * This function finishes processing credentials cache entries and invalidates @a cursor.
+ * This function finishes processing credential cache entries and invalidates
+ * @a cursor.
  *
- * @sa krb5_cc_next_cred()
+ * @sa krb5_cc_start_seq_get(), krb5_cc_next_cred()
  *
  * @retval 0 (always)
  */
@@ -2041,101 +2072,89 @@ krb5_error_code KRB5_CALLCONV
 krb5_cc_end_seq_get(krb5_context context, krb5_ccache cache,
                     krb5_cc_cursor *cursor);
 
-/** Remove credentials from a credentials cache.
- *
- * @param [in] context               Context structure
- * @param [in] cache                 Credentials cache handle
- * @param [in] flags                 Bitwise-ORed search flags
- * @param [in] creds                 Credentials to be matched
- *
- * @warning  This function is not implemented on UNIX'es. Returns KRB5_CC_NOSUPP.
- *
- * Valid values for search flags are:
- * @li @c KRB5_TC_MATCH_TIMES         The requested lifetime is required to be at least
- *                                    as great as that specified.
- * @li @c KRB5_TC_MATCH_IS_SKEY       The @a is_skey field much match exactly.
- * @li @c KRB5_TC_MATCH_FLAGS         The set bits in @a mcreds must match in @a creds.
- * @li @c KRB5_TC_MATCH_TIMES_EXACT   The requested lifetime must match exactly.
- * @li @c KRB5_TC_MATCH_FLAGS_EXACT   All bits in @a mcreds must match exactly.
- * @li @c KRB5_TC_MATCH_AUTHDATA      The authentication data must match.
- * @li @c KRB5_TC_MATCH_SRV_NAMEONLY  Only the name portion of the principal name must match.
- *                                    The realm field can be different. By default,
- *                                    the entire principal name must match.
- * @li @c KRB5_TC_MATCH_2ND_TKT       The second tickets must match.
- * @li @c KRB5_TC_MATCH_KTYPE         The encryption key types must match.
- * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES   Check all matching entries that have
- *                                         any supported encryption type.
+/**
+ * Remove credentials from a credential cache.
  *
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
+ * @param [in] flags            Bitwise-ORed search flags
+ * @param [in] creds            Credentials to be matched
+ *
+ * @warning This function is not implemented for some cache types.
+ *
+ * This function accepts the same flag values as krb5_cc_retrieve_cred().
+ *
+ * @retval KRB5_CC_NOSUPP Not implemented for this cache type
  * @return No matches found; Data cannot be deleted; Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_remove_cred(krb5_context context, krb5_ccache cache, krb5_flags flags,
                     krb5_creds *creds);
 
-/** Set options flags on a credentials cache.
+/**
+ * Set options flags on a credential cache.
  *
- * @param [in]     context   Context structure
- * @param [in,out] cache     Credentials cache handle
- * @param [in]     flags     Flag bit mask
+ * @param [in]     context      Library context
+ * @param [in,out] cache        Credential cache handle
+ * @param [in]     flags        Flag bit mask
  *
  * This function resets @a cache flags to @a flags.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_set_flags(krb5_context context, krb5_ccache cache, krb5_flags flags);
 
-/** Retrieve flags from a credentials cache structure.
+/**
+ * Retrieve flags from a credential cache structure.
  *
- * @param [in]  context          Context structure
- * @param [in]  cache            Credentials cache handle returned by
- *                               krb5_cc_resolve() or krb5_cc_generate_new()
- * @param [out] flags            Flag bit mask
+ * @param [in]  context         Library context
+ * @param [in]  cache           Credential cache handle
+ * @param [out] flags           Flag bit mask
  *
- * @warning For memory credential cache always returns KRB5_OK.
+ * @warning For memory credential cache always returns a flag mask of 0.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags);
 
-/** Retrieve the type of a credential cache.
+/**
+ * Retrieve the type of a credential cache.
  *
- * @param [in] context           Context structure
- * @param [in] cache             Credentials cache handle
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
  *
- * @return The type of a credential cache as an alias that should not be
- * modified or freed by the caller.
+ * @return The type of a credential cache as an alias that must not be modified
+ * or freed by the caller.
  */
 const char * KRB5_CALLCONV
 krb5_cc_get_type(krb5_context context, krb5_ccache cache);
 
-/** Move a credential cache.
- *
- * @param [in] context       Context structure
- * @param [in] src           The credential cache to move the content from
- * @param [in] dst           The credential cache to move the content to
+/**
+ * Move a credential cache.
  *
- * This function re-initializes @a dst and populates it with the credentials
- * and default principal of @a src, and then, if successful, destroys @a src.
+ * @param [in] context          Library context
+ * @param [in] src              The credential cache to move the content from
+ * @param [in] dst              The credential cache to move the content to
  *
- * krb5_ccache objects are locked internally, so no data corruption
- * will result if this routine is called on the same credential caches
- * in multiple threads.
+ * This function reinitializes @a dst and populates it with the credentials and
+ * default principal of @a src; then, if successful, destroys @a src.
  *
  * @retval
- * 0 Sucess; @a src is freed.
+ * 0 Success; @a src is closed.
  * @return
- * Kerberos error codes; @a src is still allocated, while @a dst is freed.
+ * Kerberos error codes; @a src is still allocated, while @a dst is closed.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst);
 
-/** Return a timestamp of the last modification of the credentials cache.
+/**
+ * Return a timestamp of the last modification to a credential cache.
  *
- * @param [in]  context            Context structure
- * @param [in]  ccache             Credentials cache handle
- * @param [out] change_time        The last change time of @a ccache
+ * @param [in]  context         Library context
+ * @param [in]  ccache          Credential cache handle
+ * @param [out] change_time     The last change time of @a ccache
  *
  * If an error occurs, @a change_time is set to 0.
  */
@@ -2149,28 +2168,31 @@ krb5_cc_lock(krb5_context context, krb5_ccache ccache);
 krb5_error_code KRB5_CALLCONV
 krb5_cc_unlock(krb5_context context, krb5_ccache ccache);
 
-/** Prepare to iterate over a collection of credentials caches.
+/**
+ * Prepare to iterate over the collection of known credential caches.
  *
- * @param [in]     context           Context structure
- * @param [in,out] cursor            Cursor
+ * @param [in]     context      Library context
+ * @param [in,out] cursor       Cursor
  *
- * Get a new cache iteration @a cursor that will iterate over all
- * credentials caches independent of type.
+ * Get a new cache iteration @a cursor that will iterate over all known
+ * credential caches independent of type.
  *
- * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer needed.
+ * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer
+ * needed.
  *
  * @sa krb5_cccol_cursor_next()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor);
 
-/** Get the next credentials cache in the collection.
+/**
+ * Get the next credential cache in the collection.
  *
- * @param [in]     context           Context structure
- * @param [in,out] cursor            Cursor
- * @param [out]    ccache            Credentials cache handle
+ * @param [in]     context      Library context
+ * @param [in,out] cursor       Cursor
+ * @param [out]    ccache       Credential cache handle
  *
  * @note When all caches are iterated over and the end of the list is reached,
  * @a ccache is set to NULL.
@@ -2179,37 +2201,38 @@ krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor);
  *
  * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_free()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_cursor_next(krb5_context context, krb5_cccol_cursor cursor,
                        krb5_ccache *ccache);
 
-/** Free a credentials cache collection cursor.
+/**
+ * Free a credential cache collection cursor.
  *
- * @param [in] context           Context structure
- * @param [in] cursor            Cursor
+ * @param [in] context          Library context
+ * @param [in] cursor           Cursor
  *
  * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_next()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_cursor_free(krb5_context context, krb5_cccol_cursor *cursor);
 
-/** Return a timestamp of the last modification for the cache collection.
+/**
+ * Return a timestamp of the last modification of any known credential cache.
  *
- * @param [in]  context            Context structure
- * @param [out] change_time        Last modification timestamp
+ * @param [in]  context         Library context
+ * @param [out] change_time     Last modification timestamp
  *
- * This function will go through the whole list of the credentials caches.
- * If the last modification time is successfully retrieved for the credentials
- * in the collection, it will be evaluated for being the most recent timestamp.
- * Otherwise, that particular cache will be ignored.
+ * This function returns the most recent modification time of any known
+ * credential cache, ignoring any caches which cannot supply a last
+ * modification time.
  *
- * If there are no credentials in the caches, @a change_time is set to 0.
+ * If there are no known credential caches, @a change_time is set to 0.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_last_change_time(krb5_context context, krb5_timestamp *change_time);
@@ -2220,12 +2243,13 @@ krb5_cccol_lock(krb5_context context);
 krb5_error_code KRB5_CALLCONV
 krb5_cccol_unlock(krb5_context context);
 
-/** Create a new unique credentials cache of the specified type.
+/**
+ * Create a new credential cache of the specified type with a unique name.
  *
- * @param [in]  context           Context structure
- * @param [in]  type              Credentials cache type name
- * @param [in]  hint              Unused
- * @param [out] id                Credentials cache handle
+ * @param [in]  context         Library context
+ * @param [in]  type            Credential cache type name
+ * @param [in]  hint            Unused
+ * @param [out] id              Credential cache handle
  *
  * @retval
  * 0 Success
@@ -2264,39 +2288,36 @@ typedef krb5_pointer krb5_kt_cursor;    /* XXX */
 /** Key table entry. */
 typedef struct krb5_keytab_entry_st {
     krb5_magic magic;
-    krb5_principal principal;   /**< principal of this key */
-    krb5_timestamp timestamp;   /**< time entry written to keytable */
-    krb5_kvno vno;              /**< key version number */
-    krb5_keyblock key;          /**< the secret key */
+    krb5_principal principal;   /**< Principal of this key */
+    krb5_timestamp timestamp;   /**< Time entry written to keytable */
+    krb5_kvno vno;              /**< Key version number */
+    krb5_keyblock key;          /**< The secret key */
 } krb5_keytab_entry;
 
 struct _krb5_kt;
 typedef struct _krb5_kt *krb5_keytab;
 
-/** Return a type of a key table.
- *
- * @param [in] context           Context structure
- * @param [in] keytab            Type of key table handle
- *
- * The possible results might be  "FILE", "MEMORY" etc
+/**
+ * Return the type of a key table.
  *
- * @warning The returned value must not be freed by the caller.
+ * @param [in] context          Library context
+ * @param [in] keytab           Key table handle
  *
- * @return
- * The key table prefix string.
+ * @return The type of a key table as an alias that must not be modified or
+ * freed by the caller.
  */
 const char * KRB5_CALLCONV
 krb5_kt_get_type(krb5_context context, krb5_keytab keytab);
 
-/** Get a key table name
+/**
+ * Get a key table name.
  *
- * @param [in]  context           Context structure
- * @param [in]  keytab            Key table handle
- * @param [out] name              Key table name
- * @param [in]  namelen           Maximum length to fill in name
+ * @param [in]  context         Library context
+ * @param [in]  keytab          Key table handle
+ * @param [out] name            Key table name
+ * @param [in]  namelen         Maximum length to fill in name
  *
- * Zeroes @a name and then copies the key table name including
- * its prefix and trailing delimeter.
+ * Fills in @a with the name of @a keytab including the type and delimiter.
  *
  * @sa MAX_KEYTAB_NAME_LEN
  *
@@ -2312,32 +2333,34 @@ krb5_error_code KRB5_CALLCONV
 krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name,
                  unsigned int namelen);
 
-/** Close a key table.
- *
- * @param [in] context           Context structure
- * @param [in] keytab            Key table handle
+/**
+ * Close a key table handle.
  *
- * Close a key table, invalidate its handle, and release any other resources
- * acquired during use of the key table.
- * Undo anything done by krb5_kt_resolve().
+ * @param [in] context          Library context
+ * @param [in] keytab           Key table handle
  *
  * @retval 0
  */
 krb5_error_code KRB5_CALLCONV
 krb5_kt_close(krb5_context context, krb5_keytab keytab);
 
-/** Get an entry from a key table.
+/**
+ * Get an entry from a key table.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  keytab          Key table handle
+ * @param [in]  principal       Principal name
+ * @param [in]  vno             Key version number (0 for highest available)
+ * @param [in]  enctype         Encryption type (0 zero for any enctype)
+ * @param [out] entry           Returned entry from key table
  *
- * @param [in]  context       Context structure
- * @param [in]  keytab        Key table handle
- * @param [in]  principal     Principal name
- * @param [in]  vno           Key version number
- * @param [in]  enctype       Encryption type. Use zero for any enctype.
- * @param [out] entry         Returned entry from key table
+ * Retrieve an entry from a key table which matches the @a keytab, @a
+ * principal, @a vno, and @a enctype.  If @a vno is zero, retrieve the
+ * highest-numbered kvno matching the other fields.  If @a enctype is 0, match
+ * any enctype.
  *
- * Retrieve an entry from a key table that matches the @a keytab, @a principal,
- * and @a vno.
- * The @a entry must be freed with krb5_kt_free_entry() when it is no longer needed.
+ * Use krb5_free_keytab_entry_contents() to free @a entry when it is no longer
+ * needed.
  *
  * @note If @a vno is zero, the function retrieves the highest-numbered-kvno
  * entry that matches the specified principal.
@@ -2352,15 +2375,15 @@ krb5_kt_get_entry(krb5_context context, krb5_keytab keytab,
                   krb5_const_principal principal, krb5_kvno vno,
                   krb5_enctype enctype, krb5_keytab_entry *entry);
 
-/** Start a sequential retrieve of key table entries.
+/**
+ * Start a sequential retrieval of key table entries.
  *
- * @param [in]  context           Context structure
- * @param [in]  keytab            Key table handle
- * @param [out] cursor            Cursor
+ * @param [in]  context         Library context
+ * @param [in]  keytab          Key table handle
+ * @param [out] cursor          Cursor
  *
- * Prepare to read sequentially every key in the specified key table.
- * @a cursor is incremented for next call to krb5_kt_next_entry().
- * The function krb5_kt_end_seq_get() should be called to release the cursor.
+ * Prepare to read sequentially every key in the specified key table.  Use
+ * krb5_kt_end_seq_get() to release the cursor when it is no longer needed.
  *
  * @sa krb5_kt_next_entry(), krb5_kt_end_seq_get()
  *
@@ -2373,17 +2396,15 @@ krb5_error_code KRB5_CALLCONV
 krb5_kt_start_seq_get(krb5_context context, krb5_keytab keytab,
                       krb5_kt_cursor *cursor);
 
-/** Retrieve the next entry from the key table.
+/**
+ * Retrieve the next entry from the key table.
  *
- * @param [in]  context           Context structure
- * @param [in]  keytab            Key table handle
- * @param [out] entry             Returned key table entry
- * @param [in,out] cursor         The cursor created by krb5_kt_start_seq_get()
- *                                and updated by successful runs of this routine
+ * @param [in]  context         Library context
+ * @param [in]  keytab          Key table handle
+ * @param [out] entry           Returned key table entry
+ * @param [in,out] cursor       Key table cursor
  *
- * Return the next sequential entry in the specified key table and update @a cursor for
- * the next request.
- * If the key table changes during the sequential get, an error is guaranteed.
+ * Return the next sequential entry in @a keytab and advance @a cursor.
  *
  * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get()
  *
@@ -2398,13 +2419,15 @@ krb5_error_code KRB5_CALLCONV
 krb5_kt_next_entry(krb5_context context, krb5_keytab keytab,
                    krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
 
-/** Complete a series of sequential key table entry retrievals and invalidate @a cursor.
+/**
+ * Release a keytab cursor.
  *
- * @param [in]  context           Context structure
- * @param [in]  keytab            Key table handle
- * @param [out] cursor            Cursor
+ * @param [in]  context         Library context
+ * @param [in]  keytab          Key table handle
+ * @param [out] cursor          Cursor
  *
- * This function should be called to release the cursor created by krb5_kt_start_seq_get()
+ * This function should be called to release the cursor created by
+ * krb5_kt_start_seq_get().
  *
  * @retval
  * 0 Success
@@ -2423,16 +2446,17 @@ krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab,
  * begin "func-proto.h"
  */
 
-/** Create and intialize a krb5_context structure.
+/**
+ * Create a krb5 library context.
  *
- * @param [out] context           Context structure
+ * @param [out] context         Library context
  *
  * The @a context must be released by calling krb5_free_context() when
  * it is no longer needed.
  *
- * @warning Any program or module that needs the Kerberos code to not trust
- * the environment must use krb5_init_secure_context(),
- * or clean out the environment.
+ * @warning Any program or module that needs the Kerberos code to not trust the
+ * environment must use krb5_init_secure_context(), or clean out the
+ * environment.
  *
  * @retval
  * 0 Success
@@ -2442,13 +2466,13 @@ krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab,
 krb5_error_code KRB5_CALLCONV
 krb5_init_context(krb5_context *context);
 
-/** Create and initialize a krb5_context structure using only configuration files.
+/**
+ * Create a krb5 library context using only configuration files.
  *
- * @param [out] context           Context structure
+ * @param [out] context         Library context
  *
- * Initialize a context structure, using only configuration files that
- * are safe for a @c setuid program.
- * All information passed through the environment variables is ignored.
+ * Create a context structure, using only system configuration files.  All
+ * information passed through the environment variables is ignored.
  *
  * The @a context must be released by calling krb5_free_context() when
  * it is no longer needed.
@@ -2461,9 +2485,10 @@ krb5_init_context(krb5_context *context);
 krb5_error_code KRB5_CALLCONV
 krb5_init_secure_context(krb5_context *context);
 
-/** Free a krb5_context structure.
+/**
+ * Free a krb5 library context.
  *
- * @param [in] context           Context structure
+ * @param [in] context          Library context
  *
  * This function frees a @a context that was created by krb5_init_context()
  * or krb5_init_secure_context().
@@ -2471,10 +2496,11 @@ krb5_init_secure_context(krb5_context *context);
 void KRB5_CALLCONV
 krb5_free_context(krb5_context context);
 
-/** Copy a krb5_context structure.
+/**
+ * Copy a krb5_context structure.
  *
- * @param [in]  ctx           Context structure
- * @param [out] nctx_out      New "cloned" context structure
+ * @param [in]  ctx             Library context
+ * @param [out] nctx_out        New context structure
  *
  * The newly created context must be released by calling krb5_free_context()
  * when it is no longer needed.
@@ -2487,10 +2513,11 @@ krb5_free_context(krb5_context context);
 krb5_error_code KRB5_CALLCONV
 krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
 
-/** Set default TGS encryption types in a krb5_context structure.
+/**
+ * Set default TGS encryption types in a krb5_context structure.
  *
- * @param [in,out] context              Context structure
- * @param [in]     etypes               Encryption type(s) to set
+ * @param [in,out] context      Library context
+ * @param [in]     etypes       Encryption type(s) to set
  *
  * This function sets the default enctype list for TGS requests
  * made using @a context to @a etypes.
@@ -2507,26 +2534,23 @@ krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
 krb5_error_code KRB5_CALLCONV
 krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes);
 
-/** Return a list of supported encryption types.
- *
- * @param [in]  context           Context structure
- * @param [out] ktypes            Zero-terminated list of encryption types
+/**
+ * Return a list of encryption types permitted for session keys.
  *
- * This function returns the content of  @a context->tgs_etypes if it is non-NULL.
- * Otherwise, the libdefaults profile string of permitted_enctypes, if it exists.
- * Otherwise, the default enctype list that is defined as follows:
- *     ENCTYPE_AES256_CTS_HMAC_SHA1_96, ENCTYPE_AES128_CTS_HMAC_SHA1_96,
- *     ENCTYPE_DES3_CBC_SHA1, ENCTYPE_ARCFOUR_HMAC,
- *     ENCTYPE_DES_CBC_CRC, ENCTYPE_DES_CBC_MD5, ENCTYPE_DES_CBC_MD4.
+ * @param [in]  context         Library context
+ * @param [out] ktypes          Zero-terminated list of encryption types
  *
- * Use krb5_free_ktypes() to free @a ktypes when it is no longer needed.
+ * This function returns the list of encryption types permitted for session
+ * keys within @a context, as determined by configuration or by a previous call
+ * to krb5_set_default_tgs_enctypes().
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);
 
-/** Test whether the Kerberos library was built with multithread support.
+/**
+ * Test whether the Kerberos library was built with multithread support.
  *
  * @retval
  * TRUE if the library is threadsafe; FALSE otherwise
@@ -2536,61 +2560,64 @@ krb5_is_thread_safe(void);
 
 /* libkrb.spec */
 
-/** Decrypt a ticket using the specified key table.
+/**
+ * Decrypt a ticket using the specified key table.
  *
- * @param [in]     context           Context structure
- * @param [in]     kt                Key table
- * @param [in,out] ticket            Ticket to be decrypted
+ * @param [in]     context      Library context
+ * @param [in]     kt           Key table
+ * @param [in,out] ticket       Ticket to be decrypted
  *
- * This function takes a @a ticket as input and decrypts it using the
- * provided key data from @a kt. The result is placed into @a ticket->enc_part2.
+ * This function takes a @a ticket as input and decrypts it using
+ * key data from @a kt.  The result is placed into @a ticket->enc_part2.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
                                   krb5_ticket *ticket);
 
-/** Free the storage assigned to array of credentials.
+/**
+ * Free an array of credential structures.
  *
- * @param [in] context           Context structure
- * @param [in] tgts              Array of credentials to be freed
+ * @param [in] context          Library context
+ * @param [in] tgts             Null-terminated array of credentials to free
  *
  * @note The last entry in the array @a tgts must be a NULL pointer.
  */
 void KRB5_CALLCONV
 krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);
 
-#define KRB5_GC_USER_USER       1       /**< want user-user ticket */
-#define KRB5_GC_CACHED          2       /**< want cached ticket only */
-#define KRB5_GC_CANONICALIZE    4       /**< set canonicalize KDC option */
-#define KRB5_GC_NO_STORE        8       /**< do not store in credentials cache */
-#define KRB5_GC_FORWARDABLE             16  /**< acquire forwardable tickets */
-#define KRB5_GC_NO_TRANSIT_CHECK        32  /**< disable transited check */
-#define KRB5_GC_CONSTRAINED_DELEGATION  64  /**< constrained delegation */
+#define KRB5_GC_USER_USER    1  /**< Want user-user ticket */
+#define KRB5_GC_CACHED       2  /**< Want cached ticket only */
+#define KRB5_GC_CANONICALIZE 4  /**< Set canonicalize KDC option */
+#define KRB5_GC_NO_STORE     8  /**< Do not store in credential cache */
+#define KRB5_GC_FORWARDABLE             16  /**< Acquire forwardable tickets */
+#define KRB5_GC_NO_TRANSIT_CHECK        32  /**< Disable transited check */
+#define KRB5_GC_CONSTRAINED_DELEGATION  64  /**< Constrained delegation */
 
-/** Get an additional ticket.
+/**
+ * Get an additional ticket.
  *
- * @param [in]     context       Context structure
- * @param [in]     options       Options
- * @param [in,out] ccache        Credentials cache handle
- * @param [in]     in_creds      Input credentials
- * @param [out]    out_creds     Output updated credentials
+ * @param [in]     context      Library context
+ * @param [in]     options      Options
+ * @param [in,out] ccache       Credential cache handle
+ * @param [in]     in_creds     Input credentials
+ * @param [out]    out_creds    Output updated credentials
  *
- * Use the specified credentials cache or a TGS exchange to get an additional
- * ticket for the client identified by @a in_creds->client.
+ * Use @a ccache or a TGS exchange to get a service ticket matching @a
+ * in_creds.
  *
  * Valid values for @a options are:
- * @li @c KRB5_GC_CACHED   Search only credentials cache for the ticket
- * @li @c KRB5_GC_USER_USER   Return a full user to user authentication ticket
+ * @li @c KRB5_GC_CACHED     Search only credential cache for the ticket
+ * @li @c KRB5_GC_USER_USER  Return a user to user authentication ticket
  *
- * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server
- * must be filled in to specify the client and the server respectively.
- * If any special  data needs to be included in the ticket (such as restrictions
- * on how the ticket can be used), specify it in @a in_creds->authdata.
- * If there is no special data to be passed, set @a in_creds->authdata to NULL.
- * The session key type is specified in @a in_creds->keyblock.keytype,
- * if it is nonzero.
+ * @a in_creds must be non-null.  @a in_creds->client and @a in_creds->server
+ * must be filled in to specify the client and the server respectively.  If any
+ * authorization data needs to be requested for the service ticket (such as
+ * restrictions on how the ticket can be used), specify it in @a
+ * in_creds->authdata; otherwise set @a in_creds->authdata to NULL.  The
+ * session key type is specified in @a in_creds->keyblock.enctype, if it is
+ * nonzero.
  *
  * The expiration date is specified in @a in_creds->times.endtime.
  * The KDC may return tickets with an earlier expiration date.
@@ -2612,343 +2639,295 @@ krb5_get_credentials(krb5_context context, krb5_flags options,
                      krb5_ccache ccache, krb5_creds *in_creds,
                      krb5_creds **out_creds);
 
-/** Contact the KDC to validate credentials.
- *
- * @param [in]     context    Context structure
- * @param          options    Unused
- * @param [in,out] ccache     Credentials cache handle
- * @param [in]     in_creds   Request credentials
- * @param [out]    out_creds  Output credentials
- *
- * This function gets a validated credential matching @a in_creds, by
- * retrieving a matching credential from @a ccache and validating it with the
- * credential's realm's KDC. Upon successful completion the result is placed in
- * @a out_creds, the @a ccache is re-initialized and updated with a new ticket.
- * Use krb5_free_creds() to free @a out when it is no longer needed.
- *
- * @retval 0 Success; Otherwise - Kerberos error codes
- */
+/** @deprecated Replaced by krb5_get_validated_creds. */
 krb5_error_code KRB5_CALLCONV
 krb5_get_credentials_validate(krb5_context context, krb5_flags options,
                               krb5_ccache ccache, krb5_creds *in_creds,
                               krb5_creds **out_creds);
 
-/** Contact the KDC to renew credentials.
- *
- * @param [in]     context    Context structure
- * @param          options    Unused
- * @param [in,out] ccache     Credentials cache handle
- * @param [in]     in_creds   Request credentials
- * @param [out]    out_creds  Output credentials
- *
- * This function gets a renewed credential matching @a in_creds, by
- * retrieving a matching credential from @a ccache and renewing it with the
- * credential's realm's KDC. Upon successful completion the result is placed in
- * @a out_creds, the @a ccache is re-initialized and updated with a new ticket.
- * Use krb5_free_creds() to free @a out when it is no longer needed.
- *
- * @retval 0 Success; Otherwise - Kerberos error codes
- */
+/** @deprecated Replaced by krb5_get_renewed_creds. */
 krb5_error_code KRB5_CALLCONV
 krb5_get_credentials_renew(krb5_context context, krb5_flags options,
                            krb5_ccache ccache, krb5_creds *in_creds,
                            krb5_creds **out_creds);
 
-/** Format a @c KRB_AP_REQ message.
+/**
+ * Create a @c KRB_AP_REQ message.
  *
- * @param [in]     context        Context structure
- * @param [in,out] auth_context   Authentication context, containing the checksum
- *                                method to be used; a new authentication
- *                                context is returned if NULL is specified.
+ * @param [in]     context        Library context
+ * @param [in,out] auth_context   Pre-existing or newly created auth context
  * @param [in]     ap_req_options AP_OPTS_ options
- * @param [in]     service        Service name, or NULL to use string @c host
- * @param [in]     hostname       Host name, or NULL to use local host
- * @param [in]     in_data        Application data's checksum to be
- *                                included in the authenticator; specify NULL
- *                                if no checksum is to be included
- * @param [in]     ccache         Credentials cache that is to be used to obtain
- *                                credentials to the desired service.
+ * @param [in]     service        Service name, or NULL to use @c "host"
+ * @param [in]     hostname       Host name, or NULL to use local hostname
+ * @param [in]     in_data        Application data to be checksummed in the
+ *                                authenticator, or NULL
+ * @param [in]     ccache         Credential cache used to obtain credentials
+ *                                for the desired service.
  * @param [out]    outbuf         @c AP-REQ message
  *
- * Valid @a ap_req_options are:
- * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
- *                                  request used for user to user authentication.
- * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
- *                                  the reciever.
- * @li @c AP_OPTS_USE_SUBKEY      - Generate a subsession key from the current
- *                                  session key obtained from the credentials.
-
- * This function is similar to krb5_mk_req_extended() except that it
- * uses a given @a hostname, @a service and @a ccache to construct credentials.
+ * This function is similar to krb5_mk_req_extended() except that it uses a
+ * given @a hostname, @a service, and @a ccache to construct a service
+ * principal name and obtain credentials.
  *
  * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_req(krb5_context context, krb5_auth_context *auth_context,
             krb5_flags ap_req_options, char *service, char *hostname,
             krb5_data *in_data, krb5_ccache ccache, krb5_data *outbuf);
 
-/** Format a @c KRB_AP_REQ message using supplied credentials.
+/**
+ * Create a @c KRB_AP_REQ message using supplied credentials.
  *
- * @param [in]     context        Context structure
- * @param [in,out] auth_context   Authentication context, containing the checksum
- *                                method to be used; a new authentication
- *                                context is returned if NULL is specified.
+ * @param [in]     context        Library context
+ * @param [in,out] auth_context   Pre-existing or newly created auth context
  * @param [in]     ap_req_options AP_OPTS_ options
- * @param [in]     in_data        Application data's checksum to be
- *                                included in the authenticator; specify NULL
- *                                if no checksum is to be included
+ * @param [in]     in_data        Application data to be checksummed in the
+ *                                authenticator, or NULL
  * @param [in]     in_creds       Credentials for the service with valid ticket
  *                                and key
  * @param [out]    outbuf         @c AP-REQ message
  *
  * Valid @a ap_req_options are:
  * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
- *                                  request used for user to user authentication.
+ *                                  request used for user to user
+ *                                  authentication.
  * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
  *                                  the reciever.
  * @li @c AP_OPTS_USE_SUBKEY      - Generate a subsession key from the current
  *                                  session key obtained from the credentials.
  *
- * This function creates a KRB_AP_REQ message using supplied credentials
- * @a in_creds. The checksum @a in_data is included in the authenticator that
- * is part of the KRB_AP_REQ message.
- * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ * This function creates a KRB_AP_REQ message using supplied credentials @a
+ * in_creds.  @a auth_context may point to an existing auth context or to NULL,
+ * in which case a new one will be created.  If @a in_data is non-null, a
+ * checksum of it will be included in the authenticator contained in the
+ * KRB_AP_REQ message.  Use krb5_free_data_contents() to free @a outbuf when it
+ * is no longer needed.
  *
- * @note A newly generated authenticator is stored in @a auth_context with the
- * @a client and @a checksum fields nulled out, unless an error is returned.
- * (This is to prevent pointer-sharing problems; the caller should not need
- * these fields anyway, since the caller supplied them.)
- * The old @a auth_context->key is overwritten by keyblock from @a in_creds.
+ * On successful return, the authenticator is stored in @a auth_context with
+ * the @a client and @a checksum fields nulled out.  (This is to prevent
+ * pointer-sharing problems; the caller should not need these fields anyway,
+ * since the caller supplied them.)
  *
  * @sa krb5_mk_req()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_req_extended(krb5_context context, krb5_auth_context *auth_context,
                      krb5_flags ap_req_options, krb5_data *in_data,
                      krb5_creds *in_creds, krb5_data *outbuf);
 
-/** Format and encrypt a @c KRB_AP_REP message.
- *
- * @param [in]     context           Context structure
- * @param [in,out] auth_context      Authentication context
- * @param [out]    outbuf            @c AP-REP message
+/**
+ * Format and encrypt a @c KRB_AP_REP message.
  *
- * The @c AP-REP message includes the data in the @a authentp field of @a
- * auth_context, and it is encrypted using the @a key field from @a auth_context.
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [out]    outbuf       @c AP-REP message
  *
- * When successful, @a outbuf->length and @a outbuf->data are filled in with the
- * length of the @c AP-REQ message and the allocated data holding it.
+ * This function fills in @a outbuf with an AP-REP message using information
+ * from @a auth_context.
  *
- * If the flags in @a auth_context indicate that a sequence number should be used
- * (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE)
- * and the local sequence number in @a auth_context is 0, a new number will
- * be generated with krb5_generate_seq_number().
+ * If the flags in @a auth_context indicate that a sequence number should be
+ * used (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c
+ * KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequence number in @a
+ * auth_context is 0, a new number will be generated with
+ * krb5_generate_seq_number().
  *
  * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_rep(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
 
-/** Format and encrypt a @c KRB_AP_REP message for DCE RPC.
+/**
+ * Format and encrypt a @c KRB_AP_REP message for DCE RPC.
  *
- * @param [in]     context           Context structure
+ * @param [in]     context           Library context
  * @param [in,out] auth_context      Authentication context
  * @param [out]    outbuf            @c AP-REP message
  *
  * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_rep_dce(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
 
-/** Parse and decrypt a @c KRB_AP_REP message.
+/**
+ * Parse and decrypt a @c KRB_AP_REP message.
  *
- * @param [in]      context            Context structure
- * @param [in,out]  auth_context       Authentication context
- * @param [in]      inbuf              AP-REP message
- * @param [out]     repl               Decrypted reply message
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     inbuf        AP-REP message
+ * @param [out]    repl         Decrypted reply message
  *
  * This function parses, decrypts and verifies a message from @a inbuf and
  * fills in @a repl with a pointer to allocated memory containing the fields
  * from the encrypted response.
+ *
  * Use krb5_free_ap_rep_enc_part() to free @a repl when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_rep(krb5_context context, krb5_auth_context auth_context,
             const krb5_data *inbuf, krb5_ap_rep_enc_part **repl);
 
-/** Parse and decrypt a @c KRB_AP_REP message for DCE RPC.
+/**
+ * Parse and decrypt a @c KRB_AP_REP message for DCE RPC.
  *
- * @param [in]      context        Context structure
- * @param [in,out]  auth_context   Authentication context
- * @param [in]      inbuf          AP-REP message
- * @param [out]     nonce          Sequence number from the decrypted reply
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     inbuf        AP-REP message
+ * @param [out]    nonce        Sequence number from the decrypted reply
  *
  * This function parses, decrypts and verifies a message from @a inbuf and
  * fills in @a nonce with a decrypted reply sequence number.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context,
                 const krb5_data *inbuf, krb5_ui_4 *nonce);
 
-/** Format and encode a @c KRB_ERROR message.
+/**
+ * Format and encode a @c KRB_ERROR message.
  *
- * @param [in]  context           Context structure
- * @param [in]  dec_err           Error structure to be encoded
- * @param [out] enc_err           Encoded error structure
+ * @param [in]  context         Library context
+ * @param [in]  dec_err         Error structure to be encoded
+ * @param [out] enc_err         Encoded error structure
  *
- * This function creates a @c KRB_ERROR message @a enc_err suitable to be
- * sent to the remote partner instead of sending a reply message.
- * Use krb5_free_data_contents() for free @a enc_err when it is no longer needed.
+ * This function creates a @c KRB_ERROR message in @a enc_err.  Use
+ * krb5_free_data_contents() to free @a enc_err when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_error(krb5_context context, const krb5_error *dec_err,
               krb5_data *enc_err);
 
-/** Decode a @c KRB-ERROR message.
+/**
+ * Decode a @c KRB-ERROR message.
  *
- * @param [in]  context           Context structure
- * @param [in]  enc_errbuf        Encoded error message
- * @param [out] dec_error         Decoded error message
+ * @param [in]  context         Library context
+ * @param [in]  enc_errbuf      Encoded error message
+ * @param [out] dec_error       Decoded error message
  *
  * This function processes @c KRB-ERROR message @a enc_errbuf and returns
  * an allocated structure @a dec_error containing the error message.
  * Use krb5_free_error() to free @a dec_error when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf,
               krb5_error **dec_error);
 
-/** Process @c KRB-SAFE message.
+/**
+ * Process @c KRB-SAFE message.
  *
- * @param [in]     context        Context structure
- * @param [in,out] auth_context   Authentication structure
- * @param [in]     inbuf          @c KRB-SAFE message to be parsed
- * @param [out]    outbuf         Data parsed from @c KRB-SAFE message
- * @param [out]    outdata        Replay data. Specify NULL if not needed
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication structure
+ * @param [in]     inbuf        @c KRB-SAFE message to be parsed
+ * @param [out]    outbuf       Data parsed from @c KRB-SAFE message
+ * @param [out]    outdata      Replay data. Specify NULL if not needed
  *
  * This function parses a @c KRB-SAFE message, verifies its integrity, and
  * stores its data into @a outbuf.
  *
  * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or
- *       KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
- *
- * @note The @a remote_addr argument in @a auth_context argument is mandatory.
- *       It specifies the address of the sender. This address will be used
- *       to verify the sender address in the KRB-SAFE message.
- *
- * The keyblock used to verify the integrity of the message is taken from the
- * fields @a recv_subkey or @a key in @a auth_context.
- * The keyblock is chosen in the preceding order by the first one that is non-null.
- *
- * @a remote_addr and @a localaddr in @a auth_context specify
- * the full addresses (host and port) of the sender and receiver, and must be of
- * type @c ADDRTYPE_ADDRPORT.
+ *       KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
  *
- * If @a local_addr is non-null, then the address of the receiver in the message
- * must match it. Otherwise, the receiver address in the message will be checked
- * against the list of local addresses as returned by krb5_os_localaddr().
- * If the check fails, an error is returned.
+ * @note @a auth_context must have a remote address set.  This address will be
+ *       used to verify the sender address in the KRB-SAFE message.  If @a
+ *       auth_context has a local address set, it will be used to verify the
+ *       receiver address in the KRB-SAFE message if the message contains one.
+ *       Both addresses must use type @c ADDRTYPE_ADDRPORT.
  *
- * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context
- * the @a remote_seq_number field of @a auth_context is compared to the
- * sequence number for the message, and error is returned
- * if it does not match. Otherwise, the sequence number is not used.
+ * If the KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
+ * sequence number of the KRB-SAFE message is checked against the remote
+ * sequence number field of @a auth_context.  Otherwise, the sequence number is
+ * not used.
  *
- * If KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
+ * If the KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
  * then two additional checks are performed:
  * @li The timestamp in the message must be within the permitted clock skew
- *     (which is usually five minutes), or error is returned.
+ *     (which is usually five minutes).
  * @li The message must not be a replayed message field in @a auth_context.
  *
  * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_safe(krb5_context context, krb5_auth_context auth_context,
              const krb5_data *inbuf, krb5_data *outbuf,
              krb5_replay_data *outdata);
 
-/** Process a @c KRB-PRIV message.
+/**
+ * Process a @c KRB-PRIV message.
  *
- * @param [in]     context        Context structure
- * @param [in,out] auth_context   Authentication structure
- * @param [in]     inbuf          @c KRB-PRIV message to be parsed
- * @param [out]    outbuf         Data parsed from @c KRB-PRIV message
- * @param [out]    outdata        Replay data. Specify NULL if not needed
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication structure
+ * @param [in]     inbuf        @c KRB-PRIV message to be parsed
+ * @param [out]    outbuf       Data parsed from @c KRB-PRIV message
+ * @param [out]    outdata      Replay data. Specify NULL if not needed
  *
  * This function parses a @c KRB-PRIV message, verifies its integrity, and
- * stores its data into @a outbuf.
- *
- * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
- *       flag is set in @a auth_context, the @a outdata is required.
- *
- * @note The @a remote_addr argument in @a auth_context argument is mandatory.
- *       It specifies the address of the sender. This address will be used
- *       to verify the sender address in the KRB-SAFE message.
+ * stores its unencrypted data into @a outbuf.
  *
- * The keyblock used to decrypt the data and verify the integrity of the message
- * is taken from fields @a recv_subkey or @a key in @a auth_context.
- * The keyblock is chosen in the preceding order by the first one that is non-null.
+ * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c
+ *       KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, @a
+ *       outdata is required.
  *
- * If @c local_addr field of @a auth_context is non-null, the address of the
- * receiver in the message must match it. Otherwise, the receiver address in the
- * message will be checked against the list of local addresses as returned by
- * krb5_os_localaddr().
+ * @note @a auth_context must have a remote address set.  This address will be
+ *       used to verify the sender address in the KRB-PRIV message.  If @a
+ *       auth_context has a local address set, it will be used to verify the
+ *       receiver address in the KRB-PRIV message if the message contains one.
+ *       Both addresses must use type @c ADDRTYPE_ADDRPORT.
  *
- * If the @a i_vector field in @a auth_context is non-null, it is used as an
- * initialization vector for the decryption (if the encryption type of
- * the message supports initialization vectors) and its contents are replaced
- * with the last block of encrypted data in the message.
+ * If the KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
+ * sequence number of the KRB-SAFE message is checked against the remote
+ * sequence number field of @a auth_context.  Otherwise, the sequence number is
+ * not used.
  *
- * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context
- * the @a remote_seq_number field of @a auth_context is compared to the
- * sequence number for the message, and error is returned
- * if it does not match. Otherwise, the sequence number is not used.
+ * If the KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
+ * then two additional checks are performed:
+ * @li The timestamp in the message must be within the permitted clock skew
+ *     (which is usually five minutes).
+ * @li The message must not be a replayed message field in @a auth_context.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_priv(krb5_context context, krb5_auth_context auth_context,
              const krb5_data *inbuf, krb5_data *outbuf,
              krb5_replay_data *outdata);
 
-/** Convert a single-string principal name to a krb5_principal structure.
+/**
+ * Convert a string principal name to a krb5_principal structure.
  *
- * @param [in]  context    Context structure
- * @param [in]  name       Single string representation of a principal name
- * @param [out] nprincipal Principal
+ * @param [in]  context         Library context
+ * @param [in]  name            String representation of a principal name
+ * @param [out] nprincipal      Principal
  *
- * Convert a single-string representation of a principal name to a
- * krb5_principal structure.
+ * Convert a string representation of a principal name to a krb5_principal
+ * structure.
  *
- * A single-string representation of a Kerberos name consists of one
- * or more principal name components, separated by slashes, optionally followed by
- * the \@ character and a realm name.
- * If the realm name is not specified, the local realm is used.
+ * A string representation of a Kerberos name consists of one or more principal
+ * name components, separated by slashes, optionally followed by the \@
+ * character and a realm name.  If the realm name is not specified, the local
+ * realm is used.
  *
- * To use the slash and \@ symbols as part of a component (quoted)
- * instead of using them as a component separator or as a realm prefix),
- * put a  backslash (\) character in front of the symbol.
- * Similarly, newline, tab, backspace, and NULL characters
- * can be included in a component by using @a n, @a t,@a b or @a 0, respectively.
+ * To use the slash and \@ symbols as part of a component (quoted) instead of
+ * using them as a component separator or as a realm prefix), put a backslash
+ * (\) character in front of the symbol.  Similarly, newline, tab, backspace,
+ * and NULL characters can be included in a component by using @c n, @c t, @c b
+ * or @c 0, respectively.
  *
  * @note The realm in a Kerberos @a name cannot contain slash, colon,
  * or NULL characters.
@@ -2968,21 +2947,22 @@ krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincip
 #define KRB5_PRINCIPAL_PARSE_ENTERPRISE    0x4 /**< Create single-component
                                                     enterprise principle */
 
-/** Convert a single-string principal name to a krb5_principal with restrictions.
+/**
+ * Convert a string principal name to a krb5_principal with flags
  *
- * @param [in]  context    Context structure
- * @param [in]  name       Single string representation of a principal name
- * @param [in]  flags      Flag
- * @param [out] nprincipal Principal
+ * @param [in]  context         Library context
+ * @param [in]  name            String representation of a principal name
+ * @param [in]  flags           Flag
+ * @param [out] nprincipal      Principal
  *
- * Similar to krb5_parse_name(), this function  converts a single-string
- * representation of a principal name to a krb5_principal structure;
- * takes the additional flags.
+ * Similar to krb5_parse_name(), this function converts a single-string
+ * representation of a principal name to a krb5_principal structure.
  *
  * The following flags are valid:
  * @li @c KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name
  * @li @c KRB5_PRINCIPAL_PARSE_MUST_REALM - realm must be present in @a name
- * @li @c KRB5_PRINCIPAL_PARSE_ENTERPRISE - Create single-component enterprise principal
+ * @li @c KRB5_PRINCIPAL_PARSE_ENTERPRISE - create single-component enterprise
+ *                                          principal
  *
  * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
  *
@@ -2995,13 +2975,14 @@ krb5_error_code KRB5_CALLCONV
 krb5_parse_name_flags(krb5_context context, const char *name,
                       int flags, krb5_principal *nprincipal);
 
-/** Convert a krb5_principal structure to a single-string representation.
+/**
+ * Convert a krb5_principal structure to a string representation.
  *
- * @param [in]  context    Context structure
- * @param [in]  principal  Principal
- * @param [out] name       Single string representation of a Kerberos principal name
+ * @param [in]  context         Library context
+ * @param [in]  principal       Principal
+ * @param [out] name            String representation of principal name
  *
- * The resulting single-string representation uses the format and quoting conventions
+ * The resulting string representation uses the format and quoting conventions
  * described for krb5_parse_name().
  *
  * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
@@ -3015,14 +2996,16 @@ krb5_error_code KRB5_CALLCONV
 krb5_unparse_name(krb5_context context, krb5_const_principal principal,
                   register char **name);
 
-/** Convert krb5_principal structure to string format.
+/**
+ * Convert krb5_principal structure to string and length.
  *
- * @param [in]  context           Context structure
- * @param [in]  principal         Principal
- * @param [out] name              Single string format of principal name
- * @param [out] size              Size of unparsed name buffer
+ * @param [in]  context         Library context
+ * @param [in]  principal       Principal
+ * @param [out] name            String representation of principal name
+ * @param [out] size            Size of unparsed name
  *
- * @sa krb5_unparse_name()
+ * This function is similar to krb5_unparse_name(), but also returns the length
+ * of the string representation.
  *
  * @retval
  * 0 Success
@@ -3037,20 +3020,21 @@ krb5_unparse_name_ext(krb5_context context, krb5_const_principal principal,
 #define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2 /**< Omit realm always */
 #define KRB5_PRINCIPAL_UNPARSE_DISPLAY  0x4 /**< Don't escape special characters */
 
-/** Convert krb5_principal structure to a single-string with restrictions.
+/**
+ * Convert krb5_principal structure to a string with flags.
  *
- * @param [in]  context    Context structure
- * @param [in]  principal  Principal
- * @param [in]  flags      Flags
- * @param [out] name       Single string representation of a Kerberos principal name
+ * @param [in]  context         Library context
+ * @param [in]  principal       Principal
+ * @param [in]  flags           Flags
+ * @param [out] name            String representation of principal name
  *
- * Similar to krb5_unparse_name(), this function converts a krb5_principal structure
- * to a single-string representation; takes the additional flags.
+ * Similar to krb5_unparse_name(), this function converts a krb5_principal
+ * structure to a string representation.
  *
  * The following flags are valid:
- * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT -  omit realm if it is the local realm
- * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm in the principal name @a name
- * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - no quoting in the principal name @a name
+ * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm
+ * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm
+ * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - do not quote special characters
  *
  * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
  *
@@ -3063,13 +3047,14 @@ krb5_error_code KRB5_CALLCONV
 krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal,
                         int flags, char **name);
 
-/** Convert krb5_principal structure to string format with restrictions.
+/**
+ * Convert krb5_principal structure to string format with flags.
  *
- * @param [in]  context           Context structure
- * @param [in]  principal         Principal
- * @param [in]  flags             Flags
- * @param [out] name              Single string format of principal name
- * @param [out] size              Size of unparsed name buffer
+ * @param [in]  context         Library context
+ * @param [in]  principal       Principal
+ * @param [in]  flags           Flags
+ * @param [out] name            Single string format of principal name
+ * @param [out] size            Size of unparsed name buffer
  *
  * @sa krb5_unparse_name() krb5_unparse_name_flags() krb5_unparse_name_ext()
  *
@@ -3082,15 +3067,15 @@ krb5_error_code KRB5_CALLCONV
 krb5_unparse_name_flags_ext(krb5_context context, krb5_const_principal principal,
                             int flags, char **name, unsigned int *size);
 
-/** Set the realm in the current context.
- *
- * @param [in,out] context           Context structure
- * @param [in]     principal         Principal name
- * @param [in]     realm             Realm name
+/**
+ * Set the realm field of a principal
  *
- * Set the realm name part of @a principal to @a realm.
+ * @param [in,out] context      Library context
+ * @param [in]     principal    Principal name
+ * @param [in]     realm        Realm name
  *
- * @note This function frees the previous realm of @a principal.
+ * Set the realm name part of @a principal to @a realm, overwriting the
+ * previous realm.
  *
  * @retval
  * 0   Success
@@ -3101,41 +3086,44 @@ krb5_error_code KRB5_CALLCONV
 krb5_set_principal_realm(krb5_context context, krb5_principal principal,
                          const char *realm);
 
-/** Search a list of addresses for a specified address.
+/**
+ * Search a list of addresses for a specified address.
  *
- * @param context                Context structure
- * @param [in] addr              Address to search for
- * @param [in] addrlist          Address list to be searched.
- *                               Specify NULL if there is no address list
+ * @param [in] context          Library context
+ * @param [in] addr             Address to search for
+ * @param [in] addrlist         Address list to be searched (or NULL)
  *
- * @note If @a addrlist contains only a NetBIOS addresses,
- *       it will be treated as empty list.
+ * @note If @a addrlist contains only a NetBIOS addresses, it will be treated
+ *       as a null list.
  *
- * @retval
- * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE otherwise
+ * @return
+ * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE
+ * otherwise
  */
 krb5_boolean KRB5_CALLCONV_WRONG
 krb5_address_search(krb5_context context, const krb5_address *addr,
                     krb5_address *const *addrlist);
 
-/** Compare two Kerberos addresses.
+/**
+ * Compare two Kerberos addresses.
  *
- * @param context                Context structure
- * @param [in] addr1             First address to be compared
- * @param [in] addr2             Second address to be compared
+ * @param [in] context          Library context
+ * @param [in] addr1            First address to be compared
+ * @param [in] addr2            Second address to be compared
  *
- * @retval
- *  TRUE if the addresses are the same, FALSE otherwise
+ * @return
+ * TRUE if the addresses are the same, FALSE otherwise
  */
 krb5_boolean KRB5_CALLCONV
 krb5_address_compare(krb5_context context, const krb5_address *addr1,
                      const krb5_address *addr2);
 
-/** Return an ordering of the specified addresses.
+/**
+ * Return an ordering of the specified addresses.
  *
- * @param context                Context structure
- * @param [in] addr1             First address
- * @param [in] addr2             Second address
+ * @param [in] context          Library context
+ * @param [in] addr1            First address
+ * @param [in] addr2            Second address
  *
  * @retval
  *  0 The two addresses are the same
@@ -3148,11 +3136,12 @@ int KRB5_CALLCONV
 krb5_address_order(krb5_context context, const krb5_address *addr1,
                    const krb5_address *addr2);
 
-/** Compare the realms of two principals.
+/**
+ * Compare the realms of two principals.
  *
- * @param [in] context           Context structure
- * @param [in] princ1            First principal
- * @param [in] princ2            Second principal
+ * @param [in] context          Library context
+ * @param [in] princ1           First principal
+ * @param [in] princ2           Second principal
  *
  * @retval
  * TRUE if the realm names are the same; FALSE otherwise
@@ -3161,11 +3150,12 @@ krb5_boolean KRB5_CALLCONV
 krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
                    krb5_const_principal princ2);
 
-/** Compare two principals.
+/**
+ * Compare two principals.
  *
- * @param [in] context           Context structure
- * @param [in] princ1            First principal
- * @param [in] princ2            Second principal
+ * @param [in] context          Library context
+ * @param [in] princ1           First principal
+ * @param [in] princ2           Second principal
  *
  * @retval
  * TRUE if the principals are the same; FALSE otherwise
@@ -3175,14 +3165,15 @@ krb5_principal_compare(krb5_context context,
                        krb5_const_principal princ1,
                        krb5_const_principal princ2);
 
-/** Compare two principals ignoring realm components.
+/**
+ * Compare two principals ignoring realm components.
  *
- * @param [in] context           Context structure
- * @param [in] princ1            First principal
- * @param [in] princ2            Second principal
+ * @param [in] context          Library context
+ * @param [in] princ1           First principal
+ * @param [in] princ2           Second principal
  *
  * Similar to krb5_principal_compare() but do not compare the realm
- * components of the principals
+ * components of the principals.
  *
  * @retval
  * TRUE if the principals are the same; FALSE otherwise
@@ -3197,9 +3188,10 @@ krb5_principal_compare_any_realm(krb5_context context,
 #define KRB5_PRINCIPAL_COMPARE_CASEFOLD      4 /**< case-insensitive */
 #define KRB5_PRINCIPAL_COMPARE_UTF8          8 /**< treat principals as UTF-8 */
 
-/** Compare two principals with additional flags.
+/**
+ * Compare two principals with additional flags.
  *
- * @param [in] context           Context structure
+ * @param [in] context           Library context
  * @param [in] princ1            First principal
  * @param [in] princ2            Second principal
  * @param [in] flags             Flags
@@ -3221,154 +3213,163 @@ krb5_principal_compare_flags(krb5_context context,
                              krb5_const_principal princ2,
                              int flags);
 
-/** Initialize an empty @c _krb5_keyblock.
+/**
+ * Initialize an empty @c krb5_keyblock.
  *
- * @param [in]  context           Context structure
- * @param [in]  enctype           Encryption type
- * @param [in]  length            Length of keyblock
- * @param [out] out               Pointer to empty keyblock
+ * @param [in]  context         Library context
+ * @param [in]  enctype         Encryption type
+ * @param [in]  length          Length of keyblock (or 0)
+ * @param [out] out             New keyblock structure
  *
- * Initialize a new keyblock and allocate storage
- * for the contents of the key, which will be freed along
- * with the keyblock when krb5_free_keyblock is called.
- * It is legal to pass in a length of 0, in which
- * case contents are left unallocated.
- * Use krb5_free_keyblock() to free @a out when it is no longer needed.
+ * Initialize a new keyblock and allocate storage for the contents of the key.
+ * It is legal to pass in a length of 0, in which case contents are left
+ * unallocated.  Use krb5_free_keyblock() to free @a out when it is no longer
+ * needed.
  *
  * @note If @a length is set to 0, contents are left unallocated.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_keyblock(krb5_context context, krb5_enctype enctype,
                    size_t length, krb5_keyblock **out);
 
-/** Copy a keyblock.
+/**
+ * Copy a keyblock.
  *
- * @param [in]  context           Context structure
- * @param [in]  from              Keyblock to be copied
- * @param [out] to                Copy of keyblock @a from
+ * @param [in]  context         Library context
+ * @param [in]  from            Keyblock to be copied
+ * @param [out] to              Copy of keyblock @a from
  *
- * This function copies the content of @a from to @a to
- * Use krb5_free_keyblock() to free @a to when it is no longer needed.
+ * This function creates a new keyblock with the same contents as @a from.  Use
+ * krb5_free_keyblock() to free @a to when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_keyblock(krb5_context context, const krb5_keyblock *from,
                    krb5_keyblock **to);
 
-/** Copy the contents of a keyblock.
+/**
+ * Copy the contents of a keyblock.
  *
- * @param [in]  context           Context structure
- * @param [in]  from              Key to be copied
- * @param [out] to                Output key
+ * @param [in]  context         Library context
+ * @param [in]  from            Key to be copied
+ * @param [out] to              Output key
  *
- * This function copies @a from->contents to @a to.
- * Use krb5_free_keyblock_contents() to zero out and free @a to
- * when it is no longer needed.
+ * This function copies the contents of @a from to @a to.  Use
+ * krb5_free_keyblock_contents() to free @a to when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_keyblock_contents(krb5_context context, const krb5_keyblock *from,
                             krb5_keyblock *to);
 
-/** Copy a krb5_creds structure.
+/**
+ * Copy a krb5_creds structure.
  *
- * @param [in]  context           Context structure
- * @param [in]  incred            Credentials structure to be copied
- * @param [out] outcred           Copy of @a incred
+ * @param [in]  context         Library context
+ * @param [in]  incred          Credentials structure to be copied
+ * @param [out] outcred         Copy of @a incred
  *
- * This function copies the content of @a incred to @a outcred
- * Use krb5_free_creds() to free @a outcred when it is no longer needed.
+ * This function creates a new credential with the contents of @a incred.  Use
+ * krb5_free_creds() to free @a outcred when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_creds(krb5_context context, const krb5_creds *incred, krb5_creds **outcred);
 
-/** Copy a krb5_data object.
+/**
+ * Copy a krb5_data object.
  *
- * @param [in]  context           Context structure
+ * @param [in]  context           Library context
  * @param [in]  indata            Data object to be copied
  * @param [out] outdata           Copy of @a indata
  *
- * This function copies the content of @a indata to @a outdata
+ * This function creates a new krb5_data object with the contents of @a indata.
  * Use krb5_free_data() to free @a outdata when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_data(krb5_context context, const krb5_data *indata, krb5_data **outdata);
 
-/** Copy a principal.
+/**
+ * Copy a principal.
  *
- * @param [in]  context           Context structure
- * @param [in]  inprinc           Principal to be copied
- * @param [out] outprinc          Copy of @a inprinc
+ * @param [in]  context         Library context
+ * @param [in]  inprinc         Principal to be copied
+ * @param [out] outprinc        Copy of @a inprinc
  *
- * This function copies the content of @a inprinc to @a outprinc
- * Use krb5_free_principal() to free @a outprinc when it is no longer needed.
+ * This function creates a new principal structure with the contents of @a
+ * inprinc.  Use krb5_free_principal() to free @a outprinc when it is no longer
+ * needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_principal(krb5_context context, krb5_const_principal inprinc,
                     krb5_principal *outprinc);
 
-/** Copy an array of addresses.
+/**
+ * Copy an array of addresses.
  *
- * @param [in]  context           Context structure
- * @param [in]  inaddr            Array of addresses to be copied
- * @param [out] outaddr           Copy of array of addresses
+ * @param [in]  context         Library context
+ * @param [in]  inaddr          Array of addresses to be copied
+ * @param [out] outaddr         Copy of array of addresses
  *
- * This function copies the content of @a inaddr to @a outaddr.
+ * This function creates a new address array containing a copy of @a inaddr.
  * Use krb5_free_addresses() to free @a outaddr when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_addresses(krb5_context context, krb5_address *const *inaddr,
                     krb5_address ***outaddr);
 
-/** Copy a krb5_ticket structure.
+/**
+ * Copy a krb5_ticket structure.
  *
- * @param [in]  context           Context structure
- * @param [in]  from              Ticket to be copied
- * @param [out] pto               Copy of ticket
+ * @param [in]  context         Library context
+ * @param [in]  from            Ticket to be copied
+ * @param [out] pto             Copy of ticket
  *
- * This function copies the content of @a from to @a pto
- * Use krb5_free_ticket() to free @a pto when it is no longer needed.
+ * This function creates a new krb5_ticket structure containing the contents of
+ * @a from.  Use krb5_free_ticket() to free @a pto when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_ticket(krb5_context context, const krb5_ticket *from, krb5_ticket **pto);
 
-/** Copy an array of authorization data structures.
+/**
+ * Copy an authorization data list.
  *
- * @param [in]  context          Context structure
- * @param [in]  in_authdat       Array of @a krb5_authdata structures
- * @param [out] out              New array of @a krb5_authdata structures
+ * @param [in]  context         Library context
+ * @param [in]  in_authdat      List of @a krb5_authdata structures
+ * @param [out] out             New array of @a krb5_authdata structures
  *
- * This function copies the content of @a in_authdat to @a out
- * Use krb5_free_authdata() to free @a out when it is no longer needed.
+ * This function creates a new authorization data list containing a copy of @a
+ * in_authdat, which must be null-terminated.  Use krb5_free_authdata() to free
+ * @a out when it is no longer needed.
  *
  * @note The last array entry in @a in_authdat must be a NULL pointer.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_authdata(krb5_context context,
                    krb5_authdata *const *in_authdat, krb5_authdata ***out);
 
-/** Merge two authdata arrays with fresh allocation.
+/**
+ * Merge two authorization data lists into a new list.
  *
- * @param [in]  context          Context structure
- * @param [in]  inauthdat1       1st array of @a krb5_authdata structures
- * @param [in]  inauthdat2       2d array of @a krb5_authdata structures
- * @param [out] outauthdat       New array of @a krb5_authdata structures
+ * @param [in]  context         Library context
+ * @param [in]  inauthdat1      First list of @a krb5_authdata structures
+ * @param [in]  inauthdat2      Second list of @a krb5_authdata structures
+ * @param [out] outauthdat      Merged list of @a krb5_authdata structures
  *
  * Merge two authdata arrays, such as the array from a ticket
  * and authenticator.
@@ -3377,7 +3378,7 @@ krb5_copy_authdata(krb5_context context,
  * @note The last array entry in @a inauthdat1 and @a inauthdat2
  * must be a NULL pointer.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_merge_authdata(krb5_context context,
@@ -3385,74 +3386,80 @@ krb5_merge_authdata(krb5_context context,
                     krb5_authdata * const *inauthdat2,
                     krb5_authdata ***outauthdat);
 
-/** Copy a krb5_authenticator srtucture.
+/**
+ * Copy a krb5_authenticator structure.
  *
- * @param [in]  context           Context structure
- * @param [in]  authfrom          krb5_authenticator structure to be copied
- * @param [out] authto            Copy of krb5_authenticator structure
+ * @param [in]  context         Library context
+ * @param [in]  authfrom        krb5_authenticator structure to be copied
+ * @param [out] authto          Copy of krb5_authenticator structure
  *
- * This function copies the content of @a authfrom to @a authto
- * Use krb5_free_authenticator() to free @a authto when it is no longer needed.
+ * This function creates a new krb5_authenticator structure with the content of
+ * @a authfrom.  Use krb5_free_authenticator() to free @a authto when it is no
+ * longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_authenticator(krb5_context context, const krb5_authenticator *authfrom,
                         krb5_authenticator **authto);
 
-/**  Copy a krb5_checksum structure.
+/**
+ * Copy a krb5_checksum structure.
  *
- * @param [in]  context           Context structure
- * @param [in]  ckfrom            Checksum to be copied
- * @param [out] ckto              Copy of krb5_checksum structure
+ * @param [in]  context         Library context
+ * @param [in]  ckfrom          Checksum to be copied
+ * @param [out] ckto            Copy of krb5_checksum structure
  *
- * This function copies the content of @a ckfrom to @a ckto
- * Use krb5_free_checksum() to free @a ckto when it is no longer needed.
+ * This function creates a new krb5_checksum structure with the contents of @a
+ * ckfrom.  Use krb5_free_checksum() to free @a ckto when it is no longer
+ * needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_copy_checksum(krb5_context context, const krb5_checksum *ckfrom,
                    krb5_checksum **ckto);
 
-/** Generate a replay cache object for server use and open it.
+/**
+ * Generate a replay cache object for server use and open it.
  *
- * @param [in]  context           Context structure
- * @param [in]  piece             Unique identifier for replay cache
- * @param [out] rcptr             Handle to an open rcache
+ * @param [in]  context         Library context
+ * @param [in]  piece           Unique identifier for replay cache
+ * @param [out] rcptr           Handle to an open rcache
  *
- * This function generates a replay cache name, allocates memory for its
- * handle @a rcptr, and then opens it. Unique identifier @a piece is used
- * to differentiate this replay cache from the others on the system and
- * typically it is the first component of the principal name of the caller.
- * The handle @a rcptr should be closed with krb5_rc_close().
- * Use krb5_rc_destroy() to destroy @a rcptr when it is no longer needed.
+ * This function generates a replay cache name based on @a piece and opens a
+ * handle to it.  Typically @a piece is the first component of the service
+ * principal name.  Use krb5_rc_close() to close @a rcptr when it is no longer
+ * needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_server_rcache(krb5_context context, const krb5_data *piece,
                        krb5_rcache *rcptr);
 
-/** Build a principal name using length-counted strings.
+/**
+ * Build a principal name using length-counted strings.
  *
- * @param [in]  context  Context structure
+ * @param [in]  context  Library context
  * @param [out] princ    Principal name
  * @param [in]  rlen     Realm name length
  * @param [in]  realm    Realm name
- * @param [in]  ...      List of arguments specifying length and content for each argument
+ * @param [in]  ...      List of unsigned int/char * components, followed by 0
  *
- * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed.
- *
- * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
- * krb5_build_principal() takes variadic arguments.
- * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
+ * This function creates a principal from a length-counted string and a
+ * variable-length list of length-counted components.  The list of components
+ * ends with the first 0 length argument (so it is not possible to specify an
+ * empty component with this function).  Call krb5_free_principal() to free
+ * allocated memory for principal when it is no longer needed.
  *
  * @code
  * Example of how to build principal WELLKNOWN/ANONYMOUS@R
  *     krb5_build_principal_ext(context, &principal, strlen("R"), "R",
- *         strlen(KRB5_WELLKNOWN_NAMESTR), KRB5_WELLKNOWN_NAMESTR,
- *         strlen(KRB5_ANONYMOUS_PRINCSTR), KRB5_ANONYMOUS_PRINCSTR, 0);
+ *         (unsigned int)strlen(KRB5_WELLKNOWN_NAMESTR),
+ *         KRB5_WELLKNOWN_NAMESTR,
+ *         (unsigned int)strlen(KRB5_ANONYMOUS_PRINCSTR),
+ *         KRB5_ANONYMOUS_PRINCSTR, 0);
  * @endcode
  *
  * @retval
@@ -3464,19 +3471,20 @@ krb5_error_code KRB5_CALLCONV_C
 krb5_build_principal_ext(krb5_context context,  krb5_principal * princ,
                          unsigned int rlen, const char * realm, ...);
 
-/** Build a principal name using null-terminated strings.
+/**
+ * Build a principal name using null-terminated strings.
  *
- * @param [in]  context           Context structure
- * @param [out] princ             Principal name
- * @param [in]  rlen              Realm name length
- * @param [in]  realm             Realm name
- * @param [in]  ...               List of len1, sl1, len2, sl2...
+ * @param [in]  context         Library context
+ * @param [out] princ           Principal name
+ * @param [in]  rlen            Realm name length
+ * @param [in]  realm           Realm name
+ * @param [in]  ...             List of char * components, ending with NULL
  *
  * Call krb5_free_principal() to free @a princ when it is no longer needed.
  *
- * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
- * krb5_build_principal() takes variadic arguments.
- * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
+ * @note krb5_build_principal() and krb5_build_principal_alloc_va() perform the
+ * same task.  krb5_build_principal() takes variadic arguments.
+ * krb5_build_principal_alloc_va() takes a pre-computed @a varargs pointer.
  *
  * @code
  * Example of how to build principal H/S@R
@@ -3499,25 +3507,7 @@ krb5_build_principal(krb5_context context,
 #endif
     ;
 #if KRB5_DEPRECATED
-/**
- * @param [in]  context           Context structure
- * @param [out] princ             Principal structure
- * @param [in]  rlen              Realm name length
- * @param [in]  realm             Realm name
- * @param [in]  ap                @c va_list of argument
- *
- * @deprecated Replaced by krb5_build_principal() and krb5_build_principal_va().
- *
- * Build a principal name, using a precomputed @c va_list.
- *
- * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
- * krb5_build_principal() takes variadic arguments.
- * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
- *
- * Use krb5_free_principal() to free @a princ when it is no longer needed.
- *
- * @retval 0 Success; otherwise - Kerberos error codes
- */
+/** @deprecated Replaced by krb5_build_principal_alloc_va(). */
 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
 krb5_build_principal_va(krb5_context context,
                         krb5_principal princ,
@@ -3526,18 +3516,20 @@ krb5_build_principal_va(krb5_context context,
                         va_list ap);
 #endif
 
-/** Build a principal name, using a precomputed variable argument list
+/**
+ * Build a principal name, using a precomputed variable argument list
  *
- * @param [in]  context           Context structure
- * @param [out] princ             Principal structure. Locally allocated.
- * @param [in]  rlen              Realm name length
- * @param [in]  realm             Realm name
- * @param [in]  ap                @c va_list of arguments
+ * @param [in]  context         Library context
+ * @param [out] princ           Principal structure
+ * @param [in]  rlen            Realm name length
+ * @param [in]  realm           Realm name
+ * @param [in]  ap              List of char * components, ending with NULL
  *
- * Similar to krb5_build_principal() this function builds a principal name,
- * but its name components are specified as va_list.
+ * Similar to krb5_build_principal(), this function builds a principal name,
+ * but its name components are specified as a va_list.
  *
- * Use krb5_free_principal() to deallocate the @a princ when it is no longer needed.
+ * Use krb5_free_principal() to deallocate @a princ when it is no longer
+ * needed.
  *
  * @code
  * Function usage example:
@@ -3559,35 +3551,38 @@ krb5_build_principal_alloc_va(krb5_context context,
                               const char *realm,
                               va_list ap);
 
-/** Convert a Kerberos V4 principal to a Kerberos V5 principal.
+/**
+ * Convert a Kerberos V4 principal to a Kerberos V5 principal.
  *
- * @param [in]  context           Context structure
- * @param [in]  name              V4 name
- * @param [in]  instance          V4 instance
- * @param [in]  realm             Realm
- * @param [out] princ             V5 principal
+ * @param [in]  context         Library context
+ * @param [in]  name            V4 name
+ * @param [in]  instance        V4 instance
+ * @param [in]  realm           Realm
+ * @param [out] princ           V5 principal
  *
  * This function builds a @a princ from V4 specification based on given input
  * @a name.instance\@realm.
  *
  * Use krb5_free_principal() to free @a princ when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_425_conv_principal(krb5_context context, const char *name,
                         const char *instance, const char *realm,
                         krb5_principal *princ);
 
-/** Convert a Kerberos V5  principal to a Kerberos V4 principal.
+/**
+ * Convert a Kerberos V5 principal to a Kerberos V4 principal.
  *
- * @param [in]  context           Context structure
- * @param [in]  princ             V5 Principal
- * @param [out] name              V4 principal's name to be filled in
- * @param [out] inst              V4 principal's instance name to be filled in
- * @param [out] realm             Principal's realm name to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  princ           V5 Principal
+ * @param [out] name            V4 principal's name to be filled in
+ * @param [out] inst            V4 principal's instance name to be filled in
+ * @param [out] realm           Principal's realm name to be filled in
  *
- * This function separates a V5 principal @a princ into @a name, @a instance, and @a realm.
+ * This function separates a V5 principal @a princ into @a name, @a instance,
+ * and @a realm.
  *
  * @retval
  *  0  Success
@@ -3606,11 +3601,12 @@ krb5_524_conv_principal(krb5_context context, krb5_const_principal princ,
  */
 struct credentials;
 
-/** Convert a Kerberos V5 credentials to a Kerberos V4 credentials
+/**
+ * Convert a Kerberos V5 credentials to a Kerberos V4 credentials
  *
  * @note Not implemented
  *
- * @retval  KRB524_KRB4_DISABLED (always)
+ * @retval KRB524_KRB4_DISABLED (always)
  */
 int KRB5_CALLCONV
 krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
@@ -3623,17 +3619,19 @@ krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
 
 /* libkt.spec */
 
-/** Get a handle for a key table.
+/**
+ * Get a handle for a key table.
  *
- * @param [in]  context           Context structure
- * @param [in]  name              Name of the key table
- * @param [out] ktid              Key table handle
+ * @param [in]  context         Library context
+ * @param [in]  name            Name of the key table
+ * @param [out] ktid            Key table handle
  *
- * Resolve the key table name @a name and fill in a handle identifying the key table.
- * The key table is not opened.
+ * Resolve the key table name @a name and fill in a handle identifying the key
+ * table.  The key table is not opened.
  *
- * @note @a name must be of the form @c type:residual, where @a type must be a type known
- * to the library and @a residual portion should be specific to the particular keytab type.
+ * @note @a name must be of the form @c type:residual, where @a type must be a
+ * type known to the library and @a residual portion should be specific to the
+ * particular keytab type.
  *
  * @sa krb5_kt_close()
  *
@@ -3649,17 +3647,15 @@ krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
 krb5_error_code KRB5_CALLCONV
 krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid);
 
-/** Get default key table name.
+/**
+ * Get default key table name.
  *
- * @param [in]     context           Context structure
- * @param [in,out] name              Key table name to be resolved
- * @param [in]     name_size         Size of @a name to return
+ * @param [in]     context      Library context
+ * @param [in,out] name         Key table name to be resolved
+ * @param [in]     name_size    Size of @a name to return
  *
- * Fill @a name with the first @a name_size bytes of the name of the
- * default key table for the current user. The name is obtained either
- * from the environment variable KRB5_KTNAME or from @a default_keytab_name
- * entry in @a libdefaults section of krb5 configuration file or
- * falls back on the default keytab name for the OS.
+ * Fill @a name with the first @a name_size bytes of the name of the default
+ * key table for the current user.
  *
  * @sa MAX_KEYTAB_NAME_LEN
  *
@@ -3673,10 +3669,11 @@ krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid);
 krb5_error_code KRB5_CALLCONV
 krb5_kt_default_name(krb5_context context, char *name, int name_size);
 
-/** Resolve default key table.
+/**
+ * Resolve default key table.
  *
- * @param [in]  context           Context structure
- * @param [in,out] id             Key table handle
+ * @param [in]  context         Library context
+ * @param [in,out] id           Key table handle
  *
  * Fill @a keytab with the default key table's @a handle.
  *
@@ -3688,26 +3685,20 @@ krb5_kt_default_name(krb5_context context, char *name, int name_size);
 krb5_error_code KRB5_CALLCONV
 krb5_kt_default(krb5_context context, krb5_keytab *id);
 
-/** Free the contents of a key table entry.
+/**
+ * Free the contents of a key table entry.
  *
- * @param [in] context           Context structure
- * @param [in] entry             Key table entry whose contents are to be freed
+ * @param [in] context          Library context
+ * @param [in] entry            Key table entry whose contents are to be freed
  *
  * @note The pointer is not freed.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_free_keytab_entry_contents(krb5_context context, krb5_keytab_entry *entry);
 
-/** Free the contents of a key table entry.
- *
- * @param [in] context           Context structure
- * @param [in] entry             Key table entry to be freed
- *
- * @warning  Use krb5_free_keytab_entry_contents instead; this does the same
- * thing but is misnamed and retained for backward compatability.
- */
+/** @deprecated Use krb5_free_keytab_entry_contents instead. */
 krb5_error_code KRB5_CALLCONV
 krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
 
@@ -3715,11 +3706,12 @@ krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
 /* remove and add are functions, so that they can return NOWRITE
    if not a writable keytab */
 
-/** Remove an entry from a key table.
+/**
+ * Remove an entry from a key table.
  *
- * @param [in] context           Context structure
- * @param [in] id                Key table handle
- * @param [in] entry             Entry to remove from key table
+ * @param [in] context          Library context
+ * @param [in] id               Key table handle
+ * @param [in] entry            Entry to remove from key table
  *
  * @retval
  * 0 Success
@@ -3731,11 +3723,12 @@ krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
 krb5_error_code KRB5_CALLCONV
 krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
 
-/** Add a new entry to a key table.
+/**
+ * Add a new entry to a key table.
  *
- * @param [in] context           Context structure
- * @param [in] id                Key table handle
- * @param [in] entry             Entry to be added
+ * @param [in] context          Library context
+ * @param [in] id               Key table handle
+ * @param [in] entry            Entry to be added
  *
  * @retval
  * 0  Success
@@ -3749,13 +3742,14 @@ krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *en
 krb5_error_code KRB5_CALLCONV
 krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
 
-/** Convert a principal name into the default salt for that principal.
+/**
+ * Convert a principal name into the default salt for that principal.
  *
- * @param [in]  context           Context structure
- * @param [in]  pr                Principal name
- * @param [out] ret               Default salt for @a pr to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  pr              Principal name
+ * @param [out] ret             Default salt for @a pr to be filled in
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV_WRONG
 krb5_principal2salt(krb5_context context,
@@ -3764,16 +3758,17 @@ krb5_principal2salt(krb5_context context,
 
 /* libcc.spec */
 
-/** Resolve a credentials cache name.
+/**
+ * Resolve a credential cache name.
  *
- * @param [in]  context          Context structure
- * @param [in]  name             Credentials cache name to be resolved
- * @param [out] cache            Credentials cache handle
+ * @param [in]  context         Library context
+ * @param [in]  name            Credential cache name to be resolved
+ * @param [out] cache           Credential cache handle
  *
- * Fills in @a cache with a @a cache handle that corresponds to the name in @a name.
- * @a name should be of the form @c type:residual,
- * and @a type must be a type known to the library.
- * If the @a name does not contain a colon, interpret it as a file name.
+ * Fills in @a cache with a @a cache handle that corresponds to the name in @a
+ * name.  @a name should be of the form @c type:residual, and @a type must be a
+ * type known to the library.  If the @a name does not contain a colon,
+ * interpret it as a file name.
  *
  * @code
  * Example: krb5_cc_resolve(context, "MEMORY:C_", &cache);
@@ -3787,11 +3782,12 @@ krb5_principal2salt(krb5_context context,
 krb5_error_code KRB5_CALLCONV
 krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache);
 
-/** Duplicate ccache handle.
+/**
+ * Duplicate ccache handle.
  *
- * @param [in]  context          Context structure
- * @param [in]  in               Credentials cache handle to be duplicated
- * @param [out] out              Credentials cache handle
+ * @param [in]  context         Library context
+ * @param [in]  in              Credential cache handle to be duplicated
+ * @param [out] out             Credential cache handle
  *
  * Create a new handle referring to the same cache as @a in.
  * The new handle and @a in can be closed independently.
@@ -3799,26 +3795,28 @@ krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache);
 krb5_error_code KRB5_CALLCONV
 krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out);
 
-/** Return the name of the default credentials cache.
+/**
+ * Return the name of the default credential cache.
  *
- * @param [in] context       Context structure
+ * @param [in] context          Library context
  *
  * Try the environment variable KRB5CCNAME first then, if it is not set,
  * fall back on the default ccache name for the OS.
  *
  * @return
- * Name of default credentials cache for the current user.
+ * Name of default credential cache for the current user.
  */
 const char *KRB5_CALLCONV
 krb5_cc_default_name(krb5_context context);
 
-/** Set the default credentials cache name.
+/**
+ * Set the default credential cache name.
  *
- * @param [in,out]  context           Context structure
- * @param [in]      name              Default credentials cache name
+ * @param [in,out]  context     Library context
+ * @param [in]      name        Default credential cache name
  *
- * This function frees the old default credentials cache name and then
- * sets it to @a name.
+ * This function frees the old default credential cache name and then sets it
+ * to @a name.
  *
  * @retval
  *  0  Success
@@ -3830,42 +3828,48 @@ krb5_cc_default_name(krb5_context context);
 krb5_error_code KRB5_CALLCONV
 krb5_cc_set_default_name(krb5_context context, const char *name);
 
-/** Resolve the default crendentials cache name.
+/**
+ * Resolve the default crendentials cache name.
  *
- * @param [in,out] context          Context structure
- * @param [out]    ccache            Pointer to credentials cache name
+ * @param [in,out] context      Library context
+ * @param [out]    ccache       Pointer to credential cache name
  *
  * @retval
  * 0  Success
  * @retval
  * KV5M_CONTEXT            Bad magic number for @c _krb5_context structure
  * @retval
- * KRB5_FCC_INTERNAL       The name of the default credentials cache cannot be obtained
+ * KRB5_FCC_INTERNAL       The name of the default credential cache cannot be
+ *                         obtained
  * @return
  * Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_default(krb5_context context, krb5_ccache *ccache);
 
-/** Copy a credentials cache.
+/**
+ * Copy a credential cache.
  *
- * @param [in]  context           Context structure
- * @param [in]  incc              Credentials cache to be copied
- * @param [out] outcc             Copy of credentials cache to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  incc            Credential cache to be copied
+ * @param [out] outcc           Copy of credential cache to be filled in
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cc_copy_creds(krb5_context context, krb5_ccache incc, krb5_ccache outcc);
 
-/** Get some configuration for the credential cache in the cache.
+/**
+ * Get a configuration value from a credential cache.
+ *
+ * @param [in]     context      Library context
+ * @param [in]     id           Credential cache handle
+ * @param [in]     principal    Configuration for this principal;
+ *                              if NULL, global for the whole cache
+ * @param [in]     key          Name of config variable
+ * @param [out]    data         Data to be fetched
  *
- * @param [in]     context     Context structure
- * @param [in]     id          The credential cache to store the data for
- * @param [in]     principal   Configuration for this principal;
- *                             if NULL, global for the whole cache.
- * @param [in]     key         Name under which the configuraion is stored
- * @param [in,out] data        Data to be fetched; free with krb5_free_data_contents()
+ * Use krb5_free_data_contents() to free @a data when it is no longer needed.
  *
  * @retval
  * 0  Success
@@ -3877,18 +3881,19 @@ krb5_cc_get_config(krb5_context context, krb5_ccache id,
                    krb5_const_principal principal,
                    const char *key, krb5_data *data);
 
-/** Store some configuration for the credential cache in the cache.
+/**
+ * Store a configuration value in a credential cache.
  *
- * @param [in,out] context         a Keberos context
- * @param [in]     id              the credential cache to store the data for.
- * @param [in]     principal       configuration for a specific principal;
- *                                 if NULL, global for the whole cache.
- * @param [in]     key             name under which the configuraion is stored.
- * @param [in]     data            data to store. If NULL, old configuration is removed.
+ * @param [in]     context      Library context
+ * @param [in]     id           Credential cache handle
+ * @param [in]     principal    Configuration for a specific principal;
+ *                              if NULL, global for the whole cache
+ * @param [in]     key          Name of config variable
+ * @param [in]     data         Data to store, or NULL to remove
  *
  * @note Existing configuration under the same key is over-written.
  *
- * @warning Before version 1.10 @a data was assumed to be always non-zero
+ * @warning Before version 1.10 @a data was assumed to be always non-null.
  *
  * @retval
  * 0  Success
@@ -3900,206 +3905,212 @@ krb5_cc_set_config(krb5_context context, krb5_ccache id,
                    krb5_const_principal principal,
                    const char *key, krb5_data *data);
 
-/** Test whether a principal is a configuration principal.
+/**
+ * Test whether a principal is a configuration principal.
  *
- * @param [in] context        a Keberos context
- * @param [in] principal      principal to check if it a configuration principal
+ * @param [in] context          Library context
+ * @param [in] principal        Principal to check
  *
  * @return
- *  TRUE (non zero) if the principal is a configuration principal
- * (generated part of krb5_cc_set_config()); FALSE (zero) otherwise.
+ * @c TRUE if the principal is a configuration principal (generated part of
+ * krb5_cc_set_config()); @c FALSE otherwise.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
 
 /* krb5_free.c */
-/** Free the storage assigned to a principal.
+/**
+ * Free the storage assigned to a principal.
  *
- * @param [in] context           Context structure
- * @param [in] val               Principal to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Principal to be freed
  */
 void KRB5_CALLCONV
 krb5_free_principal(krb5_context context, krb5_principal val);
 
-/** Free a krb5_authenticator structure.
+/**
+ * Free a krb5_authenticator structure.
  *
- * @param      context           Context structure
- * @param [in] val               Pointer to authenticator structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Authenticator structure to be freed
  *
- * This function frees the storage assigned to @a krb5_authenticator
- * structure, and then @a val itself is released.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_authenticator(krb5_context context, krb5_authenticator *val);
 
-/** Free the data stored in array of addresses.
+/**
+ * Free the data stored in array of addresses.
  *
- * @param      context           Context structure
- * @param [in] val               Array of addresses to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Array of addresses to be freed
  *
- * This function frees the storage assigned to array of @a krb5_address
- * structures, and then @a val itself is released.
+ * This function frees the contents of @a val and the array itself.
  *
  * @note The last entry in the array must be a NULL pointer.
  */
 void KRB5_CALLCONV
 krb5_free_addresses(krb5_context context, krb5_address **val);
 
-/** Free the storage assigned to array of authentication data.
+/**
+ * Free the storage assigned to array of authentication data.
  *
- * @param      context           Context structure
- * @param [in] val               Array of authentication data to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Array of authentication data to be freed
  *
- * This function frees the storage assigned to array of @a krb5_authdata
- * structures, and then @a val itself is released.
+ * This function frees the contents of @a val and the array itself.
  *
  * @note The last entry in the array must be a NULL pointer.
  */
 void KRB5_CALLCONV
 krb5_free_authdata(krb5_context context, krb5_authdata **val);
 
-/** Free a ticket.
+/**
+ * Free a ticket.
  *
- * @param [in] context           Context structure
- * @param [in] val               Ticket to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Ticket to be freed
  *
- * This function frees the storage assigned to @a krb5_ticket
- * structure, and then @a val itself is released.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_ticket(krb5_context context, krb5_ticket *val);
 
-/** Free an error allocated by either krb5_read_error() or krb5_sendauth().
+/**
+ * Free an error allocated by krb5_read_error() or krb5_sendauth().
  *
- * @param [in] context           Context structure
- * @param [in] val               Error data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Error data structure to be freed
  *
- * This function frees the storage assigned to @a krb5_error
- * structure, and then @a val itself is released.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_error(krb5_context context, register krb5_error *val);
 
-/** Free a credentials structure and invalidate its pointer.
+/**
+ * Free a krb5_creds structure.
  *
- * @param [in] context           Context structure
- * @param [in] val               Pointer to data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Credential structure to be freed.
  *
- * This function frees the storage assigned to @a krb5_creds
- * structure, and then @a val itself is released.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_creds(krb5_context context, krb5_creds *val);
 
-/** Zero out the session key and free the credentials structure.
+/**
+ * Free the contents of a krb5_creds structure.
  *
- * @param [in]     context           Context structure
- * @param [in,out] val               Pointer to the data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Credential structure to free contents of
  *
- * @note The pointer to @a val is not freed.
+ * This function frees the contents of @a val but not the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_cred_contents(krb5_context context, krb5_creds *val);
 
-/** Free a krb5_checksum structure.
+/**
+ * Free a krb5_checksum structure.
  *
- * @param      context           Context structure
- * @param [in] val               Pointer to data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Checksum structure to be freed
  *
- * This function frees the contents of a @a val and then releases @a val itself.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_checksum(krb5_context context, register krb5_checksum *val);
 
-/** Free the contents of a krb5_checksum structure.
+/**
+ * Free the contents of a krb5_checksum structure.
  *
- * @param      context           Context structure
- * @param [in] val               Checksum structure to be released
+ * @param [in] context          Library context
+ * @param [in] val              Checksum structure to free contents of
  *
- * @note The pointer to @a val itself is not freed.
+ * This function frees the contents of @a val but not the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);
 
-/** Free the storage assigned to a keyblock.
+/**
+ * Free a krb5_keyblock structure.
  *
- * @param [in] context           Context structure
- * @param [in] val               Keyblock to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Keyblock to be freed
  *
- * This function zeros out and frees the contents of a @a val and then
- * releases @a val itself.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);
 
-/** Zero out and free the contents of a keyblock.
+/**
+ * Free the contents of a krb5_keyblock structure.
  *
- * @param [in] context           Context structure
- * @param [in] key               Keyblock to be freed
+ * @param [in] context          Library context
+ * @param [in] key              Keyblock to be freed
  *
- * @note The pointer to @a key itself is not freed.
+ * This function frees the contents of @a key but not the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);
 
-/** Free the subkey keyblock.
+/**
+ * Free a krb5_ap_rep_enc_part structure.
  *
- * @param [in] context           Context structure
- * @param [in] val               Pointer to data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              AP-REP enc part to be freed
  *
- * This function frees the storage assigned to the decrypted portion of an AP-REP
- * message, and then @a val itself is released.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);
 
-/** Free the storage assigned to a krb5_data object
+/**
+ * Free a krb5_data structure.
  *
- * @param      context           Context structure
- * @param [in] val               Pointer to data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Data structure to be freed
  *
- * This function zeros out and frees the contents field of @a val and then
- * frees @a val itself.
+ * This function frees the contents of @a val and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_data(krb5_context context, krb5_data *val);
 
-/** Zero out and free the contents of a krb5_data object
+/**
+ * Free the contents of a krb_data structure.
  *
- * @param      context           Context structure
- * @param [in] val               Pointer to data structure to be freed
+ * @param [in] context          Library context
+ * @param [in] val              Data structure to free contents of
  *
- * @note The pointer to @a val itself is not freed.
+ * This function frees the contents of @a val but not the structure itself.
  */
 void KRB5_CALLCONV
 krb5_free_data_contents(krb5_context context, krb5_data *val);
 
-/** Free a simple character name string returned by krb5_unparse_name().
- *
- * @param      context           Context structure
- * @param [in] val               Pointer to name string to be freed
+/**
+ * Free a string representation of a principal.
  *
- * @note The pointer to @a val itself is not freed.
+ * @param [in] context          Library context
+ * @param [in] val              Name string to be freed
  */
 void KRB5_CALLCONV
 krb5_free_unparsed_name(krb5_context context, char *val);
 
-/** Free an array of checksum types.
- *
- * @param      context           Context structure
- * @param [in] val               Array of checksum types to be freed
+/**
+ * Free an array of checksum types.
  *
- * @note Make sure the checksum contents have already been freed.
+ * @param [in] context          Library context
+ * @param [in] val              Array of checksum types to be freed
  */
 void KRB5_CALLCONV
 krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);
 
 /* From krb5/os but needed but by the outside world */
-/** Retrieve the system time of day, in sec and ms, since the epoch.
+/**
+ * Retrieve the system time of day, in sec and ms, since the epoch.
  *
- * @param [in]  context           Context structure
- * @param [out] seconds           System timeofday, seconds portion
- * @param [out] microseconds      System timeofday, microseconds portion
+ * @param [in]  context         Library context
+ * @param [out] seconds         System timeofday, seconds portion
+ * @param [out] microseconds    System timeofday, microseconds portion
  *
  * This function retrieves the system time of day with the context
  * specific time offset adjustment.
@@ -4115,13 +4126,14 @@ krb5_error_code KRB5_CALLCONV
 krb5_us_timeofday(krb5_context context,
                   krb5_timestamp *seconds, krb5_int32 *microseconds);
 
-/** Retrieve the current time with context specific time offset adjustment.
+/**
+ * Retrieve the current time with context specific time offset adjustment.
  *
- * @param [in]     context     Context structure
- * @param [in,out] timeret     Timestamp to fill in
+ * @param [in]     context      Library context
+ * @param [in,out] timeret      Timestamp to fill in
  *
- * This function retrieves the system time of day with the context
- * specific time offset adjustment.
+ * This function retrieves the system time of day with the context specific
+ * time offset adjustment.
  *
  * @retval
  * 0  Success
@@ -4131,28 +4143,28 @@ krb5_us_timeofday(krb5_context context,
 krb5_error_code KRB5_CALLCONV
 krb5_timeofday(krb5_context context, register krb5_timestamp *timeret);
 
-/** Return all protocol addresses for this host.
- *
- * @param [in]  context       Context structure
- * @param [out] addr          Array of krb5_address pointers.
- *                            The last entry is a NULL pointer
+/**
+ * Return all interface addresses for this host.
  *
- * Compile-time configuration flags indicate which protocol family addresses
- * can be returned. Both AF_INET and AF_INET6 are currently supported.
+ * @param [in]  context         Library context
+ * @param [out] addr            Array of krb5_address pointers, ending with
+ *                              NULL
  *
  * Use krb5_free_addresses() to free @a addr when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_os_localaddr(krb5_context context, krb5_address ***addr);
 
-/** Retrieve the default realm.
+/**
+ * Retrieve the default realm.
  *
- * @param [in]  context   Context structure
- * @param [out] lrealm    Pointer to default realm for the host
+ * @param [in]  context         Library context
+ * @param [out] lrealm          Default realm name
  *
- * Retrieves the default realm to be used if no user-specified realm is available.
+ * Retrieves the default realm to be used if no user-specified realm is
+ * available.
  *
  * Use krb5_free_default_realm() to free @a lrealm when it is no longer needed.
  *
@@ -4164,10 +4176,11 @@ krb5_os_localaddr(krb5_context context, krb5_address ***addr);
 krb5_error_code KRB5_CALLCONV
 krb5_get_default_realm(krb5_context context, char **lrealm);
 
-/** Override the default realm for the specified context.
+/**
+ * Override the default realm for the specified context.
  *
- * @param [in,out] context           Context structure
- * @param [in]     lrealm            Realm name for the default realm
+ * @param [in]     context      Library context
+ * @param [in]     lrealm       Realm name for the default realm
  *
  * If @a lrealm is NULL, clear the default realm setting.
  *
@@ -4179,35 +4192,36 @@ krb5_get_default_realm(krb5_context context, char **lrealm);
 krb5_error_code KRB5_CALLCONV
 krb5_set_default_realm(krb5_context context, const char *lrealm);
 
-/** Free the default realm string returned by krb5_get_default_realm().
+/**
+ * Free a default realm string returned by krb5_get_default_realm().
  *
- * @param      context           Context structure
- * @param [in] lrealm            Realm to be freed
+ * @param [in] context          Library context
+ * @param [in] lrealm           Realm to be freed
  */
 void KRB5_CALLCONV
 krb5_free_default_realm(krb5_context context, char *lrealm);
 
-/** Generate a full principal name from a service name.
+/**
+ * Generate a full principal name from a service name.
  *
- * @param [in]  context   Context structure
- * @param [in]  hostname  Host name, or NULL to use local host
- * @param [in]  sname     Service name, or NULL to use string @c host
- * @param [in]  type      Principal type: @c KRB5_NT_SRV_HST or @c KRB5_NT_UNKNOWN
- * @param [out] ret_princ Generated principal
+ * @param [in]  context         Library context
+ * @param [in]  hostname        Host name, or NULL to use local host
+ * @param [in]  sname           Service name, or NULL to use @c "host"
+ * @param [in]  type            Principal type
+ * @param [out] ret_princ       Generated principal
  *
- * This function converts a given @a hostname and @a sname into @a krb5_principal
- * structure @a ret_princ.
+ * This function converts a @a hostname and @a sname into @a krb5_principal
+ * structure @a ret_princ.  The returned principal will be of the form @a
+ * sname\/hostname\@REALM where REALM is determined by krb5_get_host_realm().
+ * In some cases this may be the referral (empty) realm.
  *
  * The @a type can be one of the following:
  *
- * @li @c KRB5_NT_SRV_HOST canonicalizes the host name (a fully
- * qualified lowercase @a hostname using the primary name and the
- * domain name), \b before @a ret_princ is generated in the form
- * sname//hostname\@LOCAL.REALM. Most applications should use @a KRB5_NT_SRV_HOST.
+ * @li @c KRB5_NT_SRV_HOST canonicalizes the host name before looking up the
+ * realm and generating the principal.
  *
- * @li @c KRB5_NT_UNKNOWN generates a  principal name with
- * the form @a sname\/hostname\@LOCAL.REALM, but the @a hostname \b will \b not be
- * canonicalized first. It will appear exactly as it was passed in @a hostname.
+ * @li @c KRB5_NT_UNKNOWN accepts the hostname as given, and does not
+ * canonicalize it.
  *
  * Use krb5_free_principal to free @a ret_princ when it is no longer needed.
  *
@@ -4220,15 +4234,16 @@ krb5_error_code KRB5_CALLCONV
 krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname,
                         krb5_int32 type, krb5_principal *ret_princ);
 
-/** Test whether a principal matches a matching principal.
+/**
+ * Test whether a principal matches a matching principal.
  *
- * @param [in]  context        Context structure
- * @param [in]  matching       Matching principal
- * @param [in]  princ          Principal to test
+ * @param [in]  context         Library context
+ * @param [in]  matching        Matching principal
+ * @param [in]  princ           Principal to test
  *
- * @note A matching principal is a host-based principal with an empty realm and/or
- * second data component (hostname).  Profile configuration may cause the
- * hostname to be ignored even if it is present. A principal matches a
+ * @note A matching principal is a host-based principal with an empty realm
+ * and/or second data component (hostname).  Profile configuration may cause
+ * the hostname to be ignored even if it is present.  A principal matches a
  * matching principal if the former has the same non-empty (and non-ignored)
  * components of the latter.
  *
@@ -4243,14 +4258,15 @@ krb5_boolean KRB5_CALLCONV
 krb5_sname_match(krb5_context context, krb5_const_principal matching,
                  krb5_const_principal princ);
 
-/** Change a password for an existing Kerberos account.
+/**
+ * Change a password for an existing Kerberos account.
  *
- * @param [in]  context                 Context structure
- * @param [in]  creds                   Kerberos credentials to the kadmin/changepw service
- * @param [in]  newpw                   New password
- * @param [out] result_code             A numeric error code
- * @param [out] result_code_string      String equivalent to @a result_code
- * @param [out] result_string           Change password response from the KDC
+ * @param [in]  context             Library context
+ * @param [in]  creds               Credentials for kadmin/changepw service
+ * @param [in]  newpw               New password
+ * @param [out] result_code         Numeric error code from server
+ * @param [out] result_code_string  String equivalent to @a result_code
+ * @param [out] result_string       Change password response from the KDC
  *
  * Change the password for the existing principal identified by @a creds.
  *
@@ -4262,27 +4278,28 @@ krb5_sname_match(krb5_context context, krb5_const_principal matching,
  * @li KRB5_KPASSWD_AUTHERROR (3) - Authentication error
  * @li KRB5_KPASSWD_SOFTERROR (4) - Password change rejected
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_change_password(krb5_context context, krb5_creds *creds, char *newpw,
                      int *result_code, krb5_data *result_code_string,
                      krb5_data *result_string);
 
-/** Set a password for a principal using specified credentials.
+/**
+ * Set a password for a principal using specified credentials.
  *
- * @param [in,out] context            Context structure
- * @param [in]  creds                 Credentials
- * @param [in]  newpw                 New password
- * @param [in]  change_password_for   Change the password for this principal
- * @param [out] result_code           Numeric error code returned by the remote system
- * @param [out] result_code_string    Error code translated into a readable message
- * @param [out] result_string         Data returned from the remote system
+ * @param [in]  context              Library context
+ * @param [in]  creds                Credentials for kadmin/changepw service
+ * @param [in]  newpw                New password
+ * @param [in]  change_password_for  Change the password for this principal
+ * @param [out] result_code          Numeric error code from server
+ * @param [out] result_code_string   String equivalent to @a result_code
+ * @param [out] result_string        Data returned from the remote system
  *
- * This function uses the credentials @a creds to set the password
- * @a newpw for the principal @a change_password_for.
- * It implements the set password operation of RFC 3244, for
- * interoperability with Microsoft Windows implementations.
+ * This function uses the credentials @a creds to set the password @a newpw for
+ * the principal @a change_password_for.  It implements the set password
+ * operation of RFC 3244, for interoperability with Microsoft Windows
+ * implementations.
  *
  * @note If @a change_password_for is NULL, the change is performed on the
  * current principal. If @a change_password_for is non-null, the change is
@@ -4303,30 +4320,31 @@ krb5_set_password(krb5_context context, krb5_creds *creds, char *newpw,
                   krb5_principal change_password_for, int *result_code,
                   krb5_data *result_code_string, krb5_data *result_string);
 
-/** Set a password for a principal using cached credentials.
+/**
+ * Set a password for a principal using cached credentials.
  *
- * @param [in,out] context            Context structure
- * @param [in]  ccache                Credentials cache
- * @param [in]  newpw                 New password
- * @param [in]  change_password_for   Change the password for this principal
- * @param [out] result_code           Numeric error code returned by the remote system
- * @param [out] result_code_string    Error code translated into a readable message
- * @param [out] result_string         Data returned from the remote system
+ * @param [in]  context              Library context
+ * @param [in]  ccache               Credential cache
+ * @param [in]  newpw                New password
+ * @param [in]  change_password_for  Change the password for this principal
+ * @param [out] result_code          Numeric error code from server
+ * @param [out] result_code_string   String equivalent to @a result_code
+ * @param [out] result_string        Data returned from the remote system
  *
  * This function uses the cached credentials from @a ccache to set the password
- * @a newpw for the principal @a change_password_for.
- * It implements RFC 3244 set password operation (interoperable with MS Windows
- * implementations) using the credentials cache.
+ * @a newpw for the principal @a change_password_for.  It implements RFC 3244
+ * set password operation (interoperable with MS Windows implementations) using
+ * the credential cache.
  *
  * The error code and strings are returned in @a result_code,
  * @a result_code_string and @a result_string.
  *
- * @sa krb5_set_password()
- *
- * @note If @a change_password_for is set to NULL, the change is performed
- * on the default principal in @a ccache. If @a change_password_for is non null,
+ * @note If @a change_password_for is set to NULL, the change is performed on
+ * the default principal in @a ccache. If @a change_password_for is non null,
  * the change is performed on the specified principal.
  *
+ * @sa krb5_set_password()
+ *
  * @retval
  * 0  Success
  * @return
@@ -4338,9 +4356,10 @@ krb5_set_password_using_ccache(krb5_context context, krb5_ccache ccache,
                                int *result_code, krb5_data *result_code_string,
                                krb5_data *result_string);
 
-/** Retrieve configuration data from the context.
+/**
+ * Retrieve configuration profile from the context.
  *
- * @param [in]  context         Context structure
+ * @param [in]  context         Library context
  * @param [out] profile         Pointer to data read from a configuration file
  *
  * This function creates a new @a profile object that reflects profile
@@ -4384,36 +4403,39 @@ krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
 
 #endif /* KRB5_DEPRECATED */
 
-/** Parse and decrypt a @c KRB_AP_REQ message.
+/**
+ * Parse and decrypt a @c KRB_AP_REQ message.
  *
- * @param [in]     context        Context structure
- * @param [in,out] auth_context   Authentication context. A new authentication
- *                                context is returned if NULL is specified
+ * @param [in]     context        Library context
+ * @param [in,out] auth_context   Pre-existing or newly created auth context
  * @param [in]     inbuf          AP-REQ message to be parsed
- * @param [in]     server         Server's principal for the @a ticket.
- *                                Use NULL for the principal of the @a keytab
- * @param [in]     keytab         Key table that contains a decryption key.
- *                                Use NULL for the default key table.
+ * @param [in]     server         Matching principal for server, or NULL to
+ *                                allow any principal in keytab
+ * @param [in]     keytab         Key table, or NULL to use the default
  * @param [out]    ap_req_options If non-null, the AP-REQ flags on output
- * @param [out]    ticket         Returned ticket from the AP-REQ message.
- *                                Use NULL to specify that no ticket needed.
+ * @param [out]    ticket         If non-null, ticket from the AP-REQ message
  *
  * This function parses, decrypts and verifies a AP-REQ message from @a inbuf
  * and stores the authenticator in @a auth_context.
  *
- * If a keyblock is present in the @a auth_context, it is used to decrypt
- * the ticket in AP-REQ message. (This is useful for user-to-user authentication.)
- * Otherwise, the decryption key is obtained from the @a keytab.
+ * If a keyblock is present in the @a auth_context, it is used to decrypt the
+ * ticket in AP-REQ message. (This is useful for user-to-user authentication.)
+ * Otherwise, the decryption key is obtained from the @a keytab.  If @a keytab
+ * is iterable, all of its key entries it will be tried against the ticket;
+ * otherwise, the server principal in the ticket will be looked up in the
+ * keytab and that key will be tried.
  *
  * The client specified in the decrypted authenticator must match the client
- * specified in the @a ticket.
+ * specified in the decrypted ticket.  If @a server is non-null, the key in
+ * which the ticket is encrypted must correspond to a principal in @a keytab
+ * matching @a server according to the rules of krb5_sname_match().
  *
- * If the @a remote_addr field of @a auth_context is set, the request must came
+ * If the @a remote_addr field of @a auth_context is set, the request must come
  * from that address.
  *
- * If a replay cache handle is provided in the @a auth_context, the authenticator
- * and @a ticket are verified against it. If no conflicts found, the new
- * authenticator is then stored in the replay cash of @a auth_context.
+ * If a replay cache handle is provided in the @a auth_context, the
+ * authenticator and ticket are verified against it.  If no conflict is found,
+ * the new authenticator is then stored in the replay cash of @a auth_context.
  *
  * Various other checks are performed on the decoded data, including
  * cross-realm policy, clockskew, and ticket validation times.
@@ -4425,7 +4447,7 @@ krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
  *
  * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_req(krb5_context context, krb5_auth_context *auth_context,
@@ -4433,19 +4455,18 @@ krb5_rd_req(krb5_context context, krb5_auth_context *auth_context,
             krb5_keytab keytab, krb5_flags *ap_req_options,
             krb5_ticket **ticket);
 
-/** Retrieve a service key from a key table.
+/**
+ * Retrieve a service key from a key table.
  *
- * @param [in]  context     Context structure
- * @param [in]  keyprocarg  Name of a key table or NULL to use default key table
+ * @param [in]  context     Library context
+ * @param [in]  keyprocarg  Name of a key table (NULL to use default name)
  * @param [in]  principal   Service principal
- * @param [in]  vno         Key version number; use 0 to specify the key with
- *                          the highest version number
- * @param [in]  enctype     Key encryption type; use a keytype of 0 if
- *                          encryption type does not matter
- * @param [out] key         Returned service key
+ * @param [in]  vno         Key version number (0 for highest available)
+ * @param [in]  enctype     Encryption type (0 for any type)
+ * @param [out] key         Service key from key table
  *
- * Open and search the specified key table for the entry identified by @a principal, @a enctype,
- * and @a vno. If no key is found, return an error code.
+ * Open and search the specified key table for the entry identified by @a
+ * principal, @a enctype, and @a vno. If no key is found, return an error code.
  *
  * The default key table is used, unless @a keyprocarg is non-null.
  * @a keyprocarg designates a specific key table.
@@ -4461,13 +4482,14 @@ krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
                          krb5_principal principal, krb5_kvno vno,
                          krb5_enctype enctype, krb5_keyblock **key);
 
-/** Format a @c KRB-SAFE message.
+/**
+ * Format a @c KRB-SAFE message.
  *
- * @param [in]     context       Context structure
- * @param [in,out] auth_context  Authentication context
- * @param [in]     userdata      User data in the message
- * @param [out]    outbuf        Formatted @c KRB-SAFE buffer
- * @param [out]    outdata       Replay data. Specify NULL if not needed
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     userdata     User data in the message
+ * @param [out]    outbuf       Formatted @c KRB-SAFE buffer
+ * @param [out]    outdata      Replay data. Specify NULL if not needed
  *
  * This function creates an integrity protected @c KRB-SAFE message
  * using data supplied by the application.
@@ -4476,59 +4498,57 @@ krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
  * can be used to seed the checksum, full addresses (host and port) for
  * the sender and receiver, and KRB5_AUTH_CONTEXT_ flags.
  *
- * The @a local_addr field of @a auth_context is used to
- * form the addresses used in the KRB-SAFE message. The remote_addr is optional;
- * if the receiver's address is unknown, it can be replaced by NULL.
+ * The local address in @a auth_context must be set, and is used to form the
+ * sender address used in the KRB-SAFE message.  The remote address is
+ * optional; if specified, it will be used to form the receiver address used in
+ * the message.
+ *
+ * If @c KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry
+ * describing the message is entered in the replay cache @a
+ * auth_context->rcache which enables the caller to detect if this message is
+ * reflected by an attacker.  If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the
+ * replay cache is not used.
+ *
+ * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c
+ * KRB5_AUTH_CONTEXT_RET_SEQUENCE is set, the @a auth_context local sequence
+ * number will be placed in @a outdata as its sequence number.
  *
- * @note The @a local_addr argument is mandatory.
  * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or
  *       KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
  *
- * If @c KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry
- * describing the message is entered in the replay cache @a auth_context->rcache
- * which enables the caller to detect if this message is sent back by an attacker.
- * If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the replay cache is not used.
- *
- * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
- * is set, the @a auth_context local sequence number will be placed in the
- * @a outdata as its sequence number.
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_safe(krb5_context context, krb5_auth_context auth_context,
              const krb5_data *userdata, krb5_data *outbuf,
              krb5_replay_data *outdata);
 
-/** Format a @c KRB-PRIV message.
+/**
+ * Format a @c KRB-PRIV message.
  *
- * @param [in]     context       Context structure
- * @param [in,out] auth_context  Authentication context
- * @param [in]     userdata      User data for @c KRB-PRIV message
- * @param [out]    outbuf        Formatted @c KRB-PRIV message
- * @param [out]    outdata       Replay cache handle. Specify NULL if not needed.
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     userdata     User data for @c KRB-PRIV message
+ * @param [out]    outbuf       Formatted @c KRB-PRIV message
+ * @param [out]    outdata      Replay cache handle (NULL if not needed)
  *
  * This function is similar to krb5_mk_safe(), but the message is encrypted and
  * integrity-protected, not just integrity-protected.
  *
- * The @a remote_addr and @a remote_port fields of @a auth_context are
- * optional; @a local_addr, is mandatory. If the receiver's address is unknown,
- * it can be replaced by NULL.
- *
- * The encryption type is taken either from  @a send_subkey or, if NULL,
- * from @a key field of @a auth_context.
+ * The local address in @a auth_context must be set, and is used to form the
+ * sender address used in the KRB-SAFE message.  The remote address is
+ * optional; if specified, it will be used to form the receiver address used in
+ * the message.
  *
- * If the @a i_vector field in @a auth_context is non-null, it is used
- * as an initialization vector for the encryption (if the chosen encryption
- * type supports initialization vectors), and its contents are replaced with
- * the last block of encrypted data upon return.
- *
- * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
- * flag is set in @a auth_context, the @a outdata is required.
+ * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c
+ * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, the @a
+ * outdata is required.
  *
  * @note The flags from @a auth_context specify whether sequence numbers or
- * timestamps will be used to identify the message.
- * Valid values are:
+ * timestamps will be used to identify the message.  Valid values are:
+ *
  * @li @c KRB5_AUTH_CONTEXT_DO_TIME      - Use timestamps in @a outdata
  * @li @c KRB5_AUTH_CONTEXT_RET_TIME     - Copy timestamp to @a outdata.
  * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  - Use local sequence numbers from
@@ -4537,28 +4557,27 @@ krb5_mk_safe(krb5_context context, krb5_auth_context auth_context,
  *                                         @a auth_context as a sequence number
  *                                         in the encrypted message @a outbuf.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
              const krb5_data *userdata, krb5_data *outbuf,
              krb5_replay_data *outdata);
 
-/** Client function for @c sendauth protocol.
+/**
+ * Client function for @c sendauth protocol.
  *
- * @param [in]     context        Context structure
+ * @param [in]     context        Library context
  * @param [in,out] auth_context   Authentication context
  * @param [in]     fd             File descriptor that describes network socket
  * @param [in]     appl_version   Application protocol version to be matched
  *                                with the receiver's application version
- * @param [in]     client         Client principal name;
- *                                ignored if @a in_creds is non-null
- * @param [in]     server         Server principal name;
- *                                ignored if @a in_creds is non-null
+ * @param [in]     client         Client principal
+ * @param [in]     server         Server principal
  * @param [in]     ap_req_options AP_OPTS options
  * @param [in]     in_data        Data to be sent to the server
- * @param [in]     in_creds       Input credentials, or NULL to use @a ccache instead
- * @param [in]     ccache         Credentials cache
+ * @param [in]     in_creds       Input credentials, or NULL to use @a ccache
+ * @param [in]     ccache         Credential cache
  * @param [out]    error          If non-null, contains KRB_ERROR message
  *                                returned from server
  * @param [out]    rep_result     If non-null and @a ap_req_options is
@@ -4566,33 +4585,33 @@ krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
  *                                of mutual authentication exchange
  * @param [out]    out_creds      If non-null, the retrieved credentials
  *
- * This function performs the exchange by sending and receiving messages over fd.
+ * This function performs the client side of a sendauth/recvauth exchange by
+ * sending and receiving messages over @a fd.
  *
- * If @a in_creds is NULL:
- * @li @a server must be non-null
- * @li @a client can be NULL. If @a client is NULL, the credentials cache
- *      default principal is used.
+ * Credentials may be specified in three ways:
  *
- * If @a in_creds is non-null, @a in_creds->client and @a in_creds->server must be
- * filled in. If the other structure fields are filled in with valid credentials,
- * @a in_creds->ticket.length must be zero.
+ * @li If @a in_creds is NULL, credentials are obtained with
+ * krb5_get_credentials() using the principals @a client and @a server.  @a
+ * server must be non-null; @a client may NULL to use the default principal of
+ * @a ccache.
  *
- * If @a in_creds->ticket.length is nonzero, @a in_creds is used
- * as the credentials to send to the server, and @a ccache is ignored. Otherwise,
- * @a ccache is used.
+ * @li If @a in_creds is non-null but does not contain a ticket, credentials
+ * for the exchange are obtained with krb5_get_credentials() using @a in_creds.
+ * In this case, the values of @a client and @a server are unused.
  *
- * @a ccache specifies the credential cache to use only when @a in_creds is
- * NULL or @a in_creds->ticket.length is zero.
+ * @li If @a in_creds is a complete credentials structure, it used directly.
+ * In this case, the values of @a client, @a server, and @a ccache are unused.
  *
- * If the server is using a different application protocol than that specified in
- * @a appl_version, an error will be returned.
+ * If the server is using a different application protocol than that specified
+ * in @a appl_version, an error will be returned.
  *
- * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to free
- * @a rep_result and krb5_free_error() to free @a error when they are no longer needed.
+ * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to
+ * free @a rep_result, and krb5_free_error() to free @a error when they are no
+ * longer needed.
  *
  * @sa krb5_recvauth()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,
@@ -4602,50 +4621,49 @@ krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,
               krb5_error **error, krb5_ap_rep_enc_part **rep_result,
               krb5_creds **out_creds);
 
-/** Server function for @a sendauth protocol.
+/**
+ * Server function for @a sendauth protocol.
  *
- * @param [in]     context       Context structure
- * @param [in,out] auth_context  Authentication context
- * @param [in]     fd            File descriptor
- * @param [in]     appl_version  Application protocol version to be matched
- *                               against the client's application version
- * @param [in]     server        Server principal; if NULL - any server principal
- * @param [in]     flags         Additional specifications
- * @param [in]     keytab        Decryption key
- * @param [out]    ticket        Ticket (optional); only filled in with client
- *                               ticket data if non-null
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     fd           File descriptor
+ * @param [in]     appl_version Application protocol version to be matched
+ *                              against the client's application version
+ * @param [in]     server       Server principal (NULL for any in @a keytab)
+ * @param [in]     flags        Additional specifications
+ * @param [in]     keytab       Key table containing service keys
+ * @param [out]    ticket       Ticket (NULL if not needed)
  *
- * This function performs the exchange by sending and receiving messages over fd.
+ * This function performs the srever side of a sendauth/recvauth exchange by
+ * sending and receiving messages over @a fd.
  *
  * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
  *
  * @sa krb5_sendauth()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_recvauth(krb5_context context, krb5_auth_context *auth_context,
               krb5_pointer fd, char *appl_version, krb5_principal server,
               krb5_int32 flags, krb5_keytab keytab, krb5_ticket **ticket);
 
-/** Server function for @a sendauth protocol with version parameter.
+/**
+ * Server function for @a sendauth protocol with version parameter.
  *
- * @param [in]     context       Context structure
- * @param [in,out] auth_context  Authentication context
- * @param [in]     fd            File descriptor
- * @param [in]     appl_version  Application protocol version to be matched
- *                               against the client's application version
- * @param [in]     server        Server principal; if NULL - any server principal
- * @param [in]     flags         Additional specifications
- * @param [in]     keytab        Decryption key
- * @param [out]    ticket        Ticket (optional); only filled in with client
- *                               ticket data if non-null
- * @param [out]    version       If not NULL, contains the @c sendauth version
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     fd           File descriptor
+ * @param [in]     server       Server principal (NULL for any in @a keytab)
+ * @param [in]     flags        Additional specifications
+ * @param [in]     keytab       Decryption key
+ * @param [out]    ticket       Ticket (NULL if not needed)
+ * @param [out]    version      sendauth protocol version (NULL if not needed)
  *
  * This function is similar to krb5_recvauth() with the additional output
- * information place into @a version buffer.
+ * information place into @a version.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_recvauth_version(krb5_context context,
@@ -4657,24 +4675,23 @@ krb5_recvauth_version(krb5_context context,
                       krb5_ticket **ticket,
                       krb5_data *version);
 
-/** Format a @c KRB-CRED message for an array of credentials.
+/**
+ * Format a @c KRB-CRED message for an array of credentials.
  *
- * @param [in]     context            Context structure
- * @param [in,out] auth_context       Authentication context
- * @param [in]     ppcreds            NULL terminated array of credentials
- * @param [out]    ppdata             Encoded credentials
- * @param [out]    outdata            Replay cache handle.
- *                                    Specify NULL if not needed
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     ppcreds      Null-terminated array of credentials
+ * @param [out]    ppdata       Encoded credentials
+ * @param [out]    outdata      Replay cache information (NULL if not needed)
  *
  * This function takes an array of credentials @a ppcreds and formats
  * a @c KRB-CRED message @a ppdata to pass to krb5_rd_cred().
  *
  * @note If the KRB5_AUTH_CONTEXT_RET_TIME or KRB5_AUTH_CONTEXT_RET_SEQUENCE
- *       flag is set in @a auth_context, the @a outdata is required.
+ *       flag is set in @a auth_context, @a outdata is required.
  *
- * The message will be decrypted and verified using the @a recv_subkey
- * field of @a auth_context if it is non-null, or by the @a key field if
- * @a recv_subkey is null or fails to decrypt the message.
+ * The message will be encrypted using the send subkey of @a auth_context if it
+ * is present, or the session key otherwise.
  *
  * @retval
  *  0 Success
@@ -4690,21 +4707,18 @@ krb5_mk_ncred(krb5_context context, krb5_auth_context auth_context,
               krb5_creds **ppcreds, krb5_data **ppdata,
               krb5_replay_data *outdata);
 
-/** Format a @c KRB-CRED message for a single set of credentials.
+/**
+ * Format a @c KRB-CRED message for a single set of credentials.
  *
- * @param [in]     context           Context structure
- * @param [in,out] auth_context      Authentication context
- * @param [in]     pcreds            Pointer to credentials
- * @param [out]    ppdata            Encoded credentials
- * @param [out]    outdata           Replay cache handle
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     pcreds       Pointer to credentials
+ * @param [out]    ppdata       Encoded credentials
+ * @param [out]    outdata      Replay cache data (NULL if not needed)
  *
  * This is a convenience function that calls krb5_mk_ncred() with a single set
  * of credentials.
  *
- * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
- * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be
- * NULL.
- *
  * @retval
  * 0 Success
  * @retval
@@ -4719,47 +4733,46 @@ krb5_mk_1cred(krb5_context context, krb5_auth_context auth_context,
               krb5_creds *pcreds, krb5_data **ppdata,
               krb5_replay_data *outdata);
 
-/** Read and validate a @c KRB-CRED message.
+/**
+ * Read and validate a @c KRB-CRED message.
  *
- * @param [in]     context          Context structure
- * @param [in,out] auth_context     Authentication context
- * @param [in]     pcreddata        @c KRB-CRED message
- * @param [out]    pppcreds         Array of forwarded credentials
- * @param [out]    outdata          Replay data
- *                                  Specify NULL if not needed.
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     pcreddata    @c KRB-CRED message
+ * @param [out]    pppcreds     Null-terminated array of forwarded credentials
+ * @param [out]    outdata      Replay data (NULL if not needed)
  *
- * @note The @a outdata argument is required if RB5_AUTH_CONTEXT_RET_TIME or
+ * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or
  *       KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
  *
- * The keyblock used to decrypt the data and verify the integrity of the message
- * is taken from fields @a recv_subkey or @a key in @a auth_context.
- * The keyblock is chosen in the preceding order by the first one that is non-null.
- * However, if the first non-null key fails to decrypt the message, the second one
- * will be used.
+ * @a pcreddata will be decrypted using the receiving subkey if it is present
+ * in @a auth_context, or the session key if the receiving subkey is not
+ * present or fails to decrypt the message.
  *
  * Use krb5_free_tgt_creds() to free @a pppcreds when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_rd_cred(krb5_context context, krb5_auth_context auth_context,
              krb5_data *pcreddata, krb5_creds ***pppcreds,
              krb5_replay_data *outdata);
 
-/** Get a forwarded TGT and format a @c KRB-CRED message.
+/**
+ * Get a forwarded TGT and format a @c KRB-CRED message.
  *
- * @param [in] context      Context structure
- * @param [in] auth_context Authentication context with the key to encrypt @a outbuf
- * @param [in] rhost        Remote host
- * @param [in] client       Client principal for the TGT
- * @param [in] server       Server principal for the TGT
- * @param [in] cc           Credentials cache handle.
- * @param [in] forwardable  Boolean indicating whether TGT should be forwardable
- * @param [out] outbuf      Output buffer containing the TGT to be filled in
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] rhost            Remote host
+ * @param [in] client           Client principal of TGT
+ * @param [in] server           Principal of server to receive TGT
+ * @param [in] cc               Credential cache handle (NULL to use default)
+ * @param [in] forwardable      Whether TGT should be forwardable
+ * @param [out] outbuf          KRB-CRED message
  *
- * Get a TGT for use at the remote host @a rhost.
- * If @a rhost is NULL, @a server service principal will be used.
- * If @a cc is NULL, the default credential cache will be used.
+ * Get a TGT for use at the remote host @a rhost and format it into a KRB-CRED
+ * message.  If @a rhost is NULL and @a server is of type @c KRB5_NT_SRV_HST,
+ * the second component of @a server will be used.
  *
  * @retval
  *  0 Success
@@ -4779,80 +4792,89 @@ krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context,
                    char *rhost, krb5_principal client, krb5_principal server,
                    krb5_ccache cc, int forwardable, krb5_data *outbuf);
 
-/** Create and initialize an authentication context.
+/**
+ * Create and initialize an authentication context.
  *
- * @param [in]  context           Context structure
- * @param [out] auth_context      Authentication context
+ * @param [in]  context         Library context
+ * @param [out] auth_context    Authentication context
  *
- * The @c _krb5_auth_context contains all data pertinent to the various authentication routines.
+ * This function creates an authentication context to hold configuration and
+ * state relevant to krb5 functions for authenticating principals and
+ * protecting messages once authentication has occurred.
  *
- * By default, @a flags for the context are set to enable the use of the replay cache
- * (KRB5_AUTH_CONTEXT_DO_TIME) but not sequence numbers.
- * Use krb5_auth_con_setflags() to change the flags.
+ * By default, flags for the context are set to enable the use of the replay
+ * cache (KRB5_AUTH_CONTEXT_DO_TIME) but not sequence numbers.  Use
+ * krb5_auth_con_setflags() to change the flags.
  *
  * The allocated @a auth_context must be freed with krb5_auth_con_free() when
  * it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_init(krb5_context context, krb5_auth_context *auth_context);
 
-/** Free a @c _krb5_auth_context structure.
+/**
+ * Free a krb5_auth_context structure.
  *
- * @param [in] context           Context structure
- * @param [in] auth_context      Authentication context to be freed
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context to be freed
  *
- * This function frees @a auth_context allocated by krb5_auth_con_init()
+ * This function frees an auth context allocated by krb5_auth_con_init().
  *
  * @retval 0  (always)
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_free(krb5_context context, krb5_auth_context auth_context);
 
-/** Set a flags field in a krb5_auth_context structure.
+/**
+ * Set a flags field in a krb5_auth_context structure.
  *
- * @param          context           Context structure
- * @param [in,out] auth_context      Authentication context
- * @param [in]     flags             Flags bit mask
+ * @param [in]     context      Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in]     flags        Flags bit mask
  *
  * Valid values for @a flags are:
- * @li @c KRB5_AUTH_CONTEXT_DO_TIME  Use timestamps
- * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure
- * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  Use sequence numbers
- * @li @c KRB5_AUTH_RET_SEQUENCE  Copy sequence numbers to output structure
+ * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
+ * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
+ * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
+ * @li @c KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
  *
  * @retval 0 (always)
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags);
 
-/** Retrieve a flags field from a krb5_auth_context structure.
+/**
+ * Retrieve flags from a krb5_auth_context structure.
  *
- * @param          context          Context structure
- * @param [in]     auth_context     Authentication context
- * @param [out]    flags            Flags bit mask
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] flags           Flags bit mask
  *
  * Valid values for @a flags are:
- * @li @c KRB5_AUTH_CONTEXT_DO_TIME      Use timestamps in the message
- * @li @c KRB5_AUTH_CONTEXT_RET_TIME     Save timestamps to output structure.
- * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  Use sequence numbers in the message
- * @li @c KRB5_AUTH_RET_SEQUENCE         Copy sequence numbers to output structure.
- *
+ * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
+ * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
+ * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
+ * @li @c KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
  *
  * @retval 0 (always)
  */
 krb5_error_code KRB5_CALLCONV
-krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 *flags);
+krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_
+                       krb5_int32 *flags);
 
-/** Set checksum_function related fields in krb5_auth_contex structure.
+/**
+ * Set a checksum callback in an auth context.
  *
- * @param context                   Context structure
- * @param [in,out] auth_context     Authentication context
- * @param [in]     func             Function to perform the checksum
- * @param [in]     data             Pointer to arbitrary to be received by @a func
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] func             Checksum callback
+ * @param [in] data             Callback argument
  *
- * The checksum data is received when krb5_mk_req_extended() calls it.
+ * Set a callback to obtain checksum data in krb5_mk_req().  The callback will
+ * be invoked after the subkey and local sequence number are stored in @a
+ * auth_context.
  *
  * @retval 0 (always)
  */
@@ -4862,12 +4884,13 @@ krb5_auth_con_set_checksum_func( krb5_context context,
                                  krb5_mk_req_checksum_func func,
                                  void *data);
 
-/** Get checksum_function related fields from krb5_auth_contex structure.
+/**
+ * Get the checksum callback from an auth context.
  *
- * @param context                Context structure
- * @param [in]  auth_context      Authentication context
- * @param [out] func              Pointer to krb5 function that performs the checksum
- * @param [out] data              Pointer to data
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] func            Checksum callback
+ * @param [out] data            Callback argument
  *
  * @retval 0 (always)
  */
@@ -4877,81 +4900,83 @@ krb5_auth_con_get_checksum_func( krb5_context context,
                                  krb5_mk_req_checksum_func *func,
                                  void **data);
 
-/** Sep the local and remote addresses in a krb5_auth_context structure.
+/**
+ * Set the local and remote addresses in an auth context.
  *
- * @param [in]     context            Context structure
- * @param [in,out] auth_context       Authentication context
- * @param [in]     local_addr         Local address
- * @param [in]     remote_addr        Remote address
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] local_addr       Local address
+ * @param [in] remote_addr      Remote address
  *
- * This function releases the storage assigned to the contents of
- * the local and remote addresses of @a auth_context structure and
- * then sets them to @a local_addr and @a remote_addr respectively.
+ * This function releases the storage assigned to the contents of the local and
+ * remote addresses of @a auth_context and then sets them to @a local_addr and
+ * @a remote_addr respectively.
  *
  * @sa krb5_auth_con_genaddrs()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV_WRONG
 krb5_auth_con_setaddrs(krb5_context context, krb5_auth_context auth_context,
                        krb5_address *local_addr, krb5_address *remote_addr);
 
-/** Retrieve address fields from a krb5_auth_con structure.
- *
- * @param [in]  context           Context structure
- * @param [in]  auth_context      Authentication context
- * @param [out] local_addr        Local address; if NULL - not requested
- * @param [out] remote_addr       Remote address; if NULL - not requested
+/**
+ * Retrieve address fields from an auth context.
  *
- * If @a local_addr or @a remote_addr is non-null, the buffers are freed and
- * then newly allocated.
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] local_addr      Local address (NULL if not needed)
+ * @param [out] remote_addr     Remote address (NULL if not needed)
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getaddrs(krb5_context context, krb5_auth_context auth_context,
                        krb5_address **local_addr, krb5_address **remote_addr);
 
-/** Set local and remote port fields in a krb5_auth_context structure.
+/**
+ * Set local and remote port fields in an auth context.
  *
- * @param [in]     context           Context structure
- * @param [in,out] auth_context      Authentication context
- * @param [in]     local_port        Local port
- * @param [in]     remote_port       Remote port
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] local_port       Local port
+ * @param [in] remote_port      Remote port
  *
- * This function releases the storage assigned to the contents of
- * the local and remote ports of @a auth_context structure and
- * then sets them to @a local_port and @a remote_port respectively.
+ * This function releases the storage assigned to the contents of the local and
+ * remote ports of @a auth_context and then sets them to @a local_port and @a
+ * remote_port respectively.
  *
  * @sa krb5_auth_con_genaddrs()
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setports(krb5_context context, krb5_auth_context auth_context,
                        krb5_address *local_port, krb5_address *remote_port);
 
-/** Set an encryption key field in a krb5_auth_context structure.
+/**
+ * Set the session key in an auth context.
  *
- * @param [in]     context          Context structure
- * @param [in,out] auth_context     Authentication context
- * @param [in]     keyblock         User key
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] keyblock         User key
  *
- * @retval 0 Success. Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setuseruserkey(krb5_context context, krb5_auth_context auth_context,
                              krb5_keyblock *keyblock);
 
-/** Retrieve an encryption key from a krb5_auth_context structure.
+/**
+ * Retrieve the session key from an auth context as a keyblock.
  *
- * @param [in]  context            Context structure
- * @param [in]  auth_context       Authentication context
- * @param [out] keyblock           Keyblock structure containing a key
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] keyblock        Session key
  *
- * This function allocates the output @a keyblock and populates it with the
- * content of @a ac->send_key.
- * Use krb5_free_keyblock() to free @a keyblock when it it no longer needed
+ * This function creates a keyblock containing the session key from @a
+ * auth_context.  Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed
  *
  * @retval 0 Success. Otherwise - Kerberos error codes
  */
@@ -4959,14 +4984,15 @@ krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getkey(krb5_context context, krb5_auth_context auth_context,
                      krb5_keyblock **keyblock);
 
-/** Get a copy of an encryption key from a krb5_auth_context structure.
+/**
+ * Retrieve the session key from an auth context.
  *
- * @param          context             Context structure
- * @param [in]     auth_context        Authentication context
- * @param [in,out] key                 Output key structure to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] key             Session key
  *
- * This function populates the output @a key with the
- * content of @a auth_context->send_subkey.
+ * This function sets @a key to the session key from @a auth_context.  Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
  *
  * @retval 0 (always)
  */
@@ -4974,72 +5000,77 @@ krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getkey_k(krb5_context context, krb5_auth_context auth_context,
                        krb5_key *key);
 
-/** Retrieve a send_subkey keyblock from a krb5_auth_context structure.
+/**
+ * Retrieve the send subkey from an auth context as a keyblock.
  *
- * @param [in]  ctx           Context structure
- * @param [in]  ac            Authentication context
- * @param [out] keyblock      Key block structure.
+ * @param [in]  ctx             Library context
+ * @param [in]  ac              Authentication context
+ * @param [out] keyblock        Send subkey
  *
- * This function allocates the output @a keyblock and populates it with the
- * content of @a ac->send_subkey.
- * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed.
+ * This function creates a keyblock containing the send subkey from @a
+ * auth_context.  Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
 
-/** Get a copy of a send_subkey key from a krb5_auth_context structure.
+/**
+ * Retrieve the send subkey from an auth context.
  *
- * @param          ctx       Context structure
- * @param [in]     ac        Authentication context
- * @param [in,out] key       Key structure to be filled in
+ * @param [in]  ctx             Library context
+ * @param [in]  ac              Authentication context
+ * @param [out] key             Send subkey
  *
- * This function populates the output @a key with the
- * content of @a auth_context->send_subkey.
+ * This function sets @a key to the send subkey from @a auth_context.  Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
  *
- * @retval 0 (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac,
                               krb5_key *key);
 
-/** Retrieve a recv_subkey keyblock from a krb5_auth_context structure.
+/**
+ * Retrieve the receiving subkey from an auth context as a keyblock.
  *
- * @param       ctx            Context structure
- * @param [in]  ac             Authentication context
- * @param [out] keyblock       Key block structure
+ * @param [in]  ctx             Library context
+ * @param [in]  ac              Authentication context
+ * @param [out] keyblock        Receiving subkey
  *
- * This function populates the output @a keyblock with the
- * content of @a auth_context->recv_subkey.
- * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed.
+ * This function creates a keyblock containing the receiving subkey from @a
+ * auth_context.  Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
 
-/** Get a copy of a recv_subkey key from a krb5_auth_context structure.
+/**
+ * Retrieve the receiving subkey from an auth context as a keyblock.
  *
- * @param          ctx       Context structure
- * @param [in]     ac        Authentication context
- * @param [in,out] key       Key block structure to be filled in
+ * @param [in]  ctx             Library context
+ * @param [in]  ac              Authentication context
+ * @param [out] key             Receiving subkey
  *
- * This function populates the output @a key with the
- * content of @a auth_context->recv_subkey.
+ * This function sets @a key to the receiving subkey from @a auth_context.  Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
  *
- * @retval 0 (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key);
 
-/** Set a send_subkey field in a krb5_auth_context structure.
+/**
+ * Set the send subkey in an auth context with a keyblock.
  *
- * @param [in]     ctx             Context structure
- * @param [in,out] ac              Authentication context
- * @param [in]     keyblock        Key to be stored in @a ac->send_subkey
+ * @param [in] ctx              Library context
+ * @param [in] ac               Authentication context
+ * @param [in] keyblock         Send subkey
  *
- * The old  @a ac->send_subkey is freed.
+ * This function sets the send subkey in @a ac to a copy of @a keyblock.
  *
  * @retval 0 Success. Otherwise - Kerberos error codes
  */
@@ -5047,44 +5078,47 @@ krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setsendsubkey(krb5_context ctx, krb5_auth_context ac,
                             krb5_keyblock *keyblock);
 
-/** Assign send_subkey field in a krb5_auth_context structure to a given key.
+/**
+ * Set the send subkey in an auth context.
  *
- * @param [in]     ctx           Context structure
- * @param [in,out] ac            Authentication context
- * @param [in]     key           Key to be assigned to @a ac->send_subkey
+ * @param [in]  ctx             Library context
+ * @param [in]  ac              Authentication context
+ * @param [out] key             Send subkey
  *
- * The old  @a ac->send_subkey is freed.
- * The @a key reference count is incremented.
+ * This function sets the send subkey in @a ac to @a key, incrementing its
+ * reference count.
  *
- * @retval 0  (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key);
 
-/** Set a recv_subkey field in a krb5_auth_context structure.
+/**
+ * Set the receiving subkey in an auth context with a keyblock.
  *
- * @param [in]     ctx           Context structure
- * @param [in,out] ac            Authentication context
- * @param [in]     keyblock      Keyblock to be stored in @a ac->recv_subkey
+ * @param [in] ctx              Library context
+ * @param [in] ac               Authentication context
+ * @param [in] keyblock         Receiving subkey
  *
- * The old  @a ac->recv_subkey is freed.
+ * This function sets the receiving subkey in @a ac to a copy of @a keyblock.
  *
- * @retval 0 Success. Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setrecvsubkey(krb5_context ctx, krb5_auth_context ac,
                             krb5_keyblock *keyblock);
 
-/** Assign recv_subkey field in a krb5_auth_context structure to a given key.
+/**
+ * Set the receiving subkey in an auth context.
  *
- * @param [in]     ctx           Context structure
- * @param [in,out] ac            Authentication context
- * @param [in]     key           Key to be assigned to @a ac->send_subkey
+ * @param [in] ctx              Library context
+ * @param [in] ac               Authentication context
+ * @param [in] key              Receiving subkey
  *
- * The old  @a ac->recv_subkey is freed.
- * The @a key reference count is incremented.
+ * This function sets the receiving subkey in @a ac to @a key, incrementing its
+ * reference count.
  *
- * @retval 0  (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setrecvsubkey_k(krb5_context ctx, krb5_auth_context ac,
@@ -5102,35 +5136,35 @@ krb5_auth_con_getremotesubkey(krb5_context context, krb5_auth_context auth_conte
                               krb5_keyblock **keyblock);
 #endif
 
-/** Retrieve a local sequence number from a krb5_auth_context structure.
+/**
+ * Retrieve the local sequence number from an auth context.
  *
- * @param          context           Context structure
- * @param [in]     auth_context      Authentication context
- * @param [in,out] seqnumber         Local sequence number to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] seqnumber       Local sequence number
  *
- * Retrieve the local sequence number used during authentication and store
- * it in the @a seqnumber.
- * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
- * for this function to have an effect.
+ * Retrieve the local sequence number from @a auth_context and return it in @a
+ * seqnumber.  The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
+ * auth_context for this function to be useful.
  *
- * @retval 0 (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context,
                                 krb5_int32 *seqnumber);
 
-/** Retrieve a remote sequence number from a krb5_auth_context structure.
+/**
+ * Retrieve the remote sequence number from an auth context.
  *
- * @param          context           Context structure
- * @param [in]     auth_context      Authentication context
- * @param [in,out] seqnumber         Remote sequence number to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] seqnumber       Remote sequence number
  *
- * Retrieve the remote sequence number used during authentication and store
- * it in the @a seqnumber.
- * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
- * for this function to have an effect.
+ * Retrieve the remote sequence number from @a auth_context and return it in @a
+ * seqnumber.  The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
+ * auth_context for this function to be useful.
  *
- * @retval 0 (always)
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getremoteseqnumber(krb5_context context, krb5_auth_context auth_context,
@@ -5146,25 +5180,32 @@ KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
 krb5_auth_con_initivector(krb5_context context, krb5_auth_context auth_context);
 #endif
 
-/** Set the replay cache field in a krb5_auth_context structure.
+/**
+ * Set the replay cache in an auth context.
  *
- * @param context                     Context structure
- * @param [in,out] auth_context       Authentication context
- * @param [in]     rcache             Replay cache haddle
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] rcache           Replay cache haddle
  *
- * @retval 0 (always)
+ * This function sets the replay cache in @a auth_context to @a rcache.  @a
+ * rcache will be closed when @a auth_context is freed, so the caller should
+ * relinguish that responsibility.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context,
                         krb5_rcache rcache);
 
-/** Retrieve rcache field from a krb5_auth_context structure.
+/**
+ * Retrieve the replay cache from an auth context.
  *
- * @param          context          Context structure
- * @param [in]     auth_context     Authentication context
- * @param [out]    rcache           Replay cache handle
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] rcache          Replay cache handle
  *
- * Set the output @a rcache to @a auth_context->rcache.
+ * This function fetches the replay cache from @a auth_context.  The caller
+ * should not close @a rcache.
  *
  * @retval 0 (always)
  */
@@ -5172,15 +5213,15 @@ krb5_error_code KRB5_CALLCONV_WRONG
 krb5_auth_con_getrcache(krb5_context context, krb5_auth_context auth_context,
                         krb5_rcache *rcache);
 
-/** Retrieve an authenticator from the authentication context.
- *
- * @param [in]  context           Context structure
- * @param [in]  auth_context      Authentication context
- * @param [out] authenticator     Authenticator
+/**
+ * Retrieve the authenticator from an auth context.
  *
- * Use krb5_free_authenticator() to free @a authenticator when it is no longer needed
+ * @param [in]  context         Library context
+ * @param [in]  auth_context    Authentication context
+ * @param [out] authenticator   Authenticator
  *
- * @sa krb5_copy_authenticator()
+ * Use krb5_free_authenticator() to free @a authenticator when it is no longer
+ * needed.
  *
  * @retval 0 Success. Otherwise - Kerberos error codes
  */
@@ -5188,17 +5229,17 @@ krb5_error_code KRB5_CALLCONV
 krb5_auth_con_getauthenticator(krb5_context context, krb5_auth_context auth_context,
                                krb5_authenticator **authenticator);
 
-/** Set a checksum types field in a krb5_auth_context structure.
+/**
+ * Set checksum type in an an auth context.
  *
- * @param context                     Context structure
- * @param [in,out]  auth_context      Authentication context
- * @param [in]      cksumtype         Checksun type
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] cksumtype        Checksum type
  *
- * Sets @a auth_context->req_cksumtype field to @a cksumtype.
- * This function is used to override the default checksum types defined in the
- * configuration file.
+ * This function sets the checksum type in @a auth_context to be used by
+ * krb5_mk_req() for the authenticator checksum.
  *
- * @retval 0 (always)
+ * @retval 0 Success. Otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_context,
@@ -5215,30 +5256,26 @@ krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_con
  */
 
 /**
- * @brief Read a password from the keyboard input.
- *
- * @param context           Context structure [input]
- * @param prompt            First user prompt when reading password [input]
- * @param prompt2           Second user prompt, or NULL to read password only once [input]
- * @param return_pwd        Returned password [output]
- * @param size_return       During input, maximum size of password;
- * during output, total number of bytes in @a return_pwd [input, output]
+ * @brief Read a password from keyboard input.
  *
- * The first *size_return bytes of the password entered are
- * returned in @a return_pwd. If fewer than *size_return bytes are entered as a password,
- * the remainder of @a return_pwd is zeroed.
- * Upon success, the total number of bytes filled in is stored in *size_return.
+ * @param [in]     context      Library context
+ * @param [in]     prompt       First user prompt when reading password
+ * @param [in]     prompt2      Second user prompt (NULL to prompt only once)
+ * @param [out]    return_pwd   Returned password
+ * @param [in,out] size_return  On input, maximum size of password; on output,
+ *                              size of password read
  *
- * @a prompt is the prompt for the first reading of a password. It is printed
- * to the terminal, and then a password is read from the keyboard. No newlines
- * or spaces are emitted between the prompt and the cursor, unless the newline/space
- * is included in the prompt.
+ * This function reads a password from keyboard input and stores it in @a
+ * return_pwd.  @a size_return should be set by the caller to the amount of
+ * storage space available in @a return_pwd; on successful return, it will be
+ * set to the length of the password read.
  *
- * If @a prompt2 is a NULL pointer, the password is read only once.
+ * @a prompt is printed to the terminal, followed by ": ", and then a password
+ * is read from the keyboard.
  *
- * If @a prompt2 is set, it is used as a prompt to read another
- * password in the same manner as described for the first password. After the
- * second password is read, the two passwords are compared, and an error is returned if they are not identical.
+ * If @a prompt2 is NULL, the password is read only once.  Otherwise, @a
+ * prompt2 is printed to the terminal and a second password is read.  If the
+ * two passwords entered are not identical, KRB5_LIBOS_BADPWDMATCH is returned.
  *
  * Echoing is turned off when the password is read.
  *
@@ -5254,19 +5291,21 @@ krb5_read_password(krb5_context context,
                    const char *prompt, const char *prompt2,
                    char *return_pwd, unsigned int *size_return);
 
-/** Convert a principal name to a local name.
+/**
+ * Convert a principal name to a local name.
  *
- * @param [in]  context           Context structure
- * @param [in]  aname             Principal name
- * @param [in]  lnsize_in         Maximum length name to be filled into @a lname
- * @param [out] lname             Local name buffer to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  aname           Principal name
+ * @param [in]  lnsize_in       Space available in @a lname
+ * @param [out] lname           Local name buffer to be filled in
  *
- * If @a aname isn't in one of the local realms an error is returned.
- * If @a lnsize_in of @a lname is to small, an error is returned.
+ * If @a aname does not correspond to any local account, KRB5_LNAME_NOTRANS is
+ * returned.  If @a lnsize_in is too small for the local name,
+ * KRB5_CONFIG_NOTENUFSPACE is returned.
  *
  * Local names, rather than principal names, can be used by programs that
- * translate to an environment-specific  name (for example, a user account
- * name). The translation is null-terminated in all non-error returns.
+ * translate to an environment-specific name (for example, a user account
+ * name).
  *
  * @retval
  * 0  Success
@@ -5279,19 +5318,21 @@ krb5_error_code KRB5_CALLCONV
 krb5_aname_to_localname(krb5_context context, krb5_const_principal aname,
                         int lnsize_in, char *lname);
 
-/** Get the Kerberos realm names for a host.
+/**
+ * Get the Kerberos realm names for a host.
  *
- * @param [in]  context           Context structure
- * @param [in]  host              Host name
- * @param [out] realmsp           Pointer to list of realm names
+ * @param [in]  context         Library context
+ * @param [in]  host            Host name (or NULL)
+ * @param [out] realmsp         Null-terminated list of realm names
  *
- * Fill in @a realmsp with a pointer to an @c argv style list of names,
- * terminated with a NULL pointer.
- * If there are no known realms for the host, the filled-in pointer is set to NULL.
+ * Fill in @a realmsp with a pointer to a null-terminated list of realm names.
+ * If there are no known realms for the host, a list containing the referral
+ * (empty) realm is returned.
  *
  * If @a host is NULL, the local host's realms are determined.
  *
- * Use krb5_free_host_realm() to release @a realmsp when it is no longer needed.
+ * Use krb5_free_host_realm() to release @a realmsp when it is no longer
+ * needed.
  *
  * @retval
  *  0   Success
@@ -5305,21 +5346,28 @@ krb5_get_host_realm(krb5_context context, const char *host, char ***realmsp);
 
 /**
  *
- * @param context           Context structure [input, output]
- * @param hdata
- * @param realmsp
+ * @param [in] context           Library context
+ * @param [in] hdata             Host name (or NULL)
+ * @param [out] realmsp          Null-terminated list of realm names
  *
- * @todo part of referrals support? param descriptions? added pointer descr.
+ * Fill in @a realmsp with a pointer to a null-terminated list of realm names
+ * obtained through heuristics or insecure resolution methods which have lower
+ * priority than KDC referrals.
+ *
+ * If @a host is NULL, the local host's realms are determined.
  *
+ * Use krb5_free_host_realm() to release @a realmsp when it is no longer
+ * needed.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_fallback_host_realm(krb5_context context,
                              krb5_data *hdata, char ***realmsp);
 
-/** Free the memory allocated by krb5_get_host_realm().
+/**
+ * Free the memory allocated by krb5_get_host_realm().
  *
- * @param      context           Context structure
- * @param [in] realmlist         List of the realm names to be released
+ * @param [in] context          Library context
+ * @param [in] realmlist        List of realm names to be released
  *
  * @retval
  * 0  Success
@@ -5329,219 +5377,231 @@ krb5_get_fallback_host_realm(krb5_context context,
 krb5_error_code KRB5_CALLCONV
 krb5_free_host_realm(krb5_context context, char *const *realmlist);
 
-/** Determine if the principal is authorized to log in as a local user.
- *
- * @param [in] context           Context structure
- * @param [in] principal         Principal name
- * @param [in] luser             Local username
+/**
+ * Determine if a principal is authorized to log in as a local user.
  *
- * Determine whether the @a principal is authorized to log in
- * as a local user @a luser
+ * @param [in] context          Library context
+ * @param [in] principal        Principal name
+ * @param [in] luser            Local username
  *
- * If there is either no local account for @a luser or @a principal does not
- * match luser\@realm for any default relam or it is not recorded in the existing
- * .k5login, the @a luser is not authorized to log into an account.
+ * Determine whether @a principal is authorized to log in as a local user @a
+ * luser.
  *
  * @retval
- * TRUE User is authorized to log in; FALSE otherwise
+ * TRUE Principal is authorized to log in as user; FALSE otherwise.
  */
 krb5_boolean KRB5_CALLCONV
 krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);
 
-/** Generate a full IP address from @a address and port.
+/**
+ * Generate auth context addresses from a connected socket.
  *
- * @param [in]     context      Context structure
- * @param [in,out] auth_context Authentication context to be updated with
- *                              new local and remote addresses.
- * @param [in]     infd         Input socket file descriptor
- * @param [in]     flags        Input flags, defined in @c KRB\$ROOT:[INCLUDE]KRB5.
+ * @param [in] context          Library context
+ * @param [in] auth_context     Authentication context
+ * @param [in] infd             Connected socket descriptor
+ * @param [in] flags            Flags
  *
- * The values for the symbols can be OR'd together. Valid values are:
+ * This function sets the local and/or remote addresses in @a auth_context
+ * based on the local and remote endpoints of the socket @a infd.  The
+ * following flags determine the operations performed:
  *
  * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
+ * Generate local address.
  * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
+ * Generate remote address.
  * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR
+ * Generate local address and port.
  * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR
+ * Generate remote address and port.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context,
                        int infd, int flags);
 
-/** Set time offset field in a krb5_context structure.
- *
- * @param [in] context           Context structure
- * @param [in] seconds           Number of seconds to set in @c time_offset
- *                               field in @a context
- * @param [in] microseconds      Number of microseconds to set in @c usec_offset
- *                               field in @a context
+/**
+ * Set time offset field in a krb5_context structure.
  *
- * Take the @a real @a time as input, and set the time offset fields in the
- * context structure so the @c krb5_time routines return the correct time,
- * as corrected by the difference between the system time and the @a real @a time as passed to this routine.
+ * @param [in] context          Library context
+ * @param [in] seconds          Real time, seconds portion
+ * @param [in] microseconds     Real time, microseconds portion
  *
- * Make sure to free the allocated memory when it is no longer needed.
+ * This function sets the time offset in @a context to the difference between
+ * the system time and the real time as determined by @a seconds and @a
+ * microseconds.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_set_real_time(krb5_context context, krb5_timestamp seconds,
                    krb5_int32 microseconds);
 
-/** Return the time offsets from the os context.
+/**
+ * Return the time offsets from the os context.
  *
- * @param [in]  context           Context structure
- * @param [out] seconds           Time offset from the OS context, seconds portion
- * @param [out] microseconds      Time offset from the OS context, microseconds portion
+ * @param [in]  context         Library context
+ * @param [out] seconds         Time offset, seconds portion
+ * @param [out] microseconds    Time offset, microseconds portion
  *
- * This function returns the time offsets from @a context->os_context.
+ * This function returns the time offsets in @a context.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_time_offsets(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds);
 
 /* str_conv.c */
-/** Convert a string to an encryption type.
+/**
+ * Convert a string to an encryption type.
  *
- * @param [in]  string        String to convert to an encryption type
- * @param [out] enctypep      Encryption type to be filled in
+ * @param [in]  string          String to convert to an encryption type
+ * @param [out] enctypep        Encryption type
  *
- * @retval 0  Success; Otherwise - EINVAL
+ * @retval 0  Success; otherwise - EINVAL
  */
 krb5_error_code KRB5_CALLCONV
 krb5_string_to_enctype(char *string, krb5_enctype *enctypep);
 
-/** Convert a string to a salt type.
+/**
+ * Convert a string to a salt type.
  *
- * @param [in]  string        String to convert to an encryption type
- * @param [out] salttypep     Salt type to be filled in
+ * @param [in]  string          String to convert to an encryption type
+ * @param [out] salttypep       Salt type to be filled in
  *
- * @retval 0  Success; Otherwise - EINVAL
+ * @retval 0  Success; otherwise - EINVAL
  */
 krb5_error_code KRB5_CALLCONV
 krb5_string_to_salttype(char *string, krb5_int32 *salttypep);
 
-/** Convert a string to a checksum type.
+/**
+ * Convert a string to a checksum type.
  *
- * @param [in]  string        String to be converted
- * @param [out] cksumtypep    Checksum type to be filled in
+ * @param [in]  string          String to be converted
+ * @param [out] cksumtypep      Checksum type to be filled in
  *
- * @retval 0  Success; Otherwise - EINVAL
+ * @retval 0  Success; otherwise - EINVAL
  */
 krb5_error_code KRB5_CALLCONV
 krb5_string_to_cksumtype(char *string, krb5_cksumtype *cksumtypep);
 
-/** Convert a string to a timestamp.
+/**
+ * Convert a string to a timestamp.
  *
- * @param [in]  string        String to be converted
- * @param [out] timestampp    Pointer to timestamp
+ * @param [in]  string          String to be converted
+ * @param [out] timestampp      Pointer to timestamp
  *
- * @retval 0  Success; Otherwise - EINVAL
+ * @retval 0  Success; otherwise - EINVAL
  */
 krb5_error_code KRB5_CALLCONV
 krb5_string_to_timestamp(char *string, krb5_timestamp *timestampp);
 
-/** Convert a string to a delta time value.
+/**
+ * Convert a string to a delta time value.
  *
- * @param [in]  string    String to be converted
- * @param [out] deltatp   Delta time to be filled in
+ * @param [in]  string          String to be converted
+ * @param [out] deltatp         Delta time to be filled in
  *
- * @retval 0  Success; Otherwise - KRB5_DELTAT_BADFORMAT
+ * @retval 0  Success; otherwise - KRB5_DELTAT_BADFORMAT
  */
 krb5_error_code KRB5_CALLCONV
 krb5_string_to_deltat(char *string, krb5_deltat *deltatp);
 
-/** Convert a Kerberos encryption type value to a string.
+/**
+ * Convert an encryption type to a string.
  *
- * @param [in]  enctype  Encrytion type value to convert
- * @param [out] buffer   Buffer to hold encryption type string
- * @param [in]  buflen   Maximum length of the string that can fit in @a buffer
+ * @param [in]  enctype         Encryption type
+ * @param [out] buffer          Buffer to hold encryption type string
+ * @param [in]  buflen          Storage available in @a buffer
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_enctype_to_string(krb5_enctype enctype, char *buffer, size_t buflen);
 
-/** Convert a Kerberos encryption type value to a name
+/**
+ * Convert an encryption type to a name or alias.
  *
- * @param [in]  enctype  Encrytion type value to convert
- * @param [in]  shortest Flag
- * @param [out] buffer   Buffer to hold encryption type string
- * @param [in]  buflen   Maximum length of the string that can fit in @a buffer
+ * @param [in]  enctype         Encryption type
+ * @param [in]  shortest        Flag
+ * @param [out] buffer          Buffer to hold encryption type string
+ * @param [in]  buflen          Storage available in @a buffer
  *
  * If @a shortest is FALSE, this function returns the enctype's canonical name
- * (like "aes128-cts-hmac-sha1-96").  If @a shortest is TRUE, it return the enctype's
- * shortest alias (like "aes128-cts").
+ * (like "aes128-cts-hmac-sha1-96").  If @a shortest is TRUE, it return the
+ * enctype's shortest alias (like "aes128-cts").
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_enctype_to_name(krb5_enctype enctype, krb5_boolean shortest,
                      char *buffer, size_t buflen);
 
-/** Convert a @a salttype to a string.
+/**
+ * Convert a salt type to a string.
  *
- * @param [in]  salttype          Salttype to convert
- * @param [out] buffer            Buffer to receive the converted string
- * @param [in]  buflen            Length of @a buffer
+ * @param [in]  salttype        Salttype to convert
+ * @param [out] buffer          Buffer to receive the converted string
+ * @param [in]  buflen          Storage available in @a buffer
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_salttype_to_string(krb5_int32 salttype, char *buffer, size_t buflen);
 
-/** Convert a checksum type to a string.
- *
- * @param [in]  cksumtype         Checksum type to be converted
- * @param [out] buffer            Buffer to hold converted checksum type
- * @param [in]  buflen            Maximum length of @a buffer
+/**
+ * Convert a checksum type to a string.
  *
- * The string is returned in the locale's appropriate date and time representation.
+ * @param [in]  cksumtype       Checksum type
+ * @param [out] buffer          Buffer to hold converted checksum type
+ * @param [in]  buflen          Storage available in @a buffer
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen);
 
-/** Convert a timestamp to a string.
+/**
+ * Convert a timestamp to a string.
  *
- * @param [in]  timestamp         Timestamp to be converted
- * @param [out] buffer            Buffer to hold converted timestamp
- * @param [in]  buflen            Maximum length of buffer
+ * @param [in]  timestamp       Timestamp to convert
+ * @param [out] buffer          Buffer to hold converted timestamp
+ * @param [in]  buflen          Storage available in @a buffer
  *
- * The string is returned in the locale's appropriate date and time representation.
+ * The string is returned in the locale's appropriate date and time
+ * representation.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_timestamp_to_string(krb5_timestamp timestamp, char *buffer, size_t buflen);
 
-/** Convert a timestamp to a string, allowing optional padding in the output buffer.
+/**
+ * Convert a timestamp to a string, with optional output padding
  *
- * @param [in]  timestamp     Timestamp to convert
- * @param [out] buffer        Buffer to hold the converted timestamp
- * @param [in]  buflen        Length of buffer
- * @param [in]  pad           Optional value to pad @a buffer
- *                            if converted timestamp does not fill it
+ * @param [in]  timestamp       Timestamp to convert
+ * @param [out] buffer          Buffer to hold the converted timestamp
+ * @param [in]  buflen          Length of buffer
+ * @param [in]  pad             Optional value to pad @a buffer if converted
+ *                              timestamp does not fill it
  *
- * This function also tries multiple possible formats if the default
- * locale-specific fails.
+ * If @a pad is not NULL, @a buffer is padded out to @a buflen - 1 characters
+ * with the value of *@a pad.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_timestamp_to_sfstring(krb5_timestamp timestamp, char *buffer,
                            size_t buflen, char *pad);
 
-/** Convert a relative time value to a string.
+/**
+ * Convert a relative time value to a string.
  *
- * @param [in]  deltat            Relative time value to convert
- * @param [out] buffer            Buffer to hold time string
- * @param [in]  buflen            Maximum length of string that fits in @a buffer
+ * @param [in]  deltat          Relative time value to convert
+ * @param [out] buffer          Buffer to hold time string
+ * @param [in]  buflen          Storage available in @a buffer
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
@@ -5557,9 +5617,9 @@ krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
 
 /** Text for prompt used in prompter callback function.  */
 typedef struct _krb5_prompt {
-    char *prompt;      /**< the prompt to show to the user */
-    int hidden;        /**< boolean; informative prompt or hidden (as for PIN or OTP) */
-    krb5_data *reply;  /**< must be allocated before call to any prompt routine */
+    char *prompt;      /**< The prompt to show to the user */
+    int hidden;        /**< Boolean; informative prompt or hidden (e.g. PIN) */
+    krb5_data *reply;  /**< Must be allocated before call to  prompt routine */
 } krb5_prompt;
 
 /** Pointer to a prompter callback function. */
@@ -5569,19 +5629,23 @@ typedef krb5_error_code
                                    int num_prompts, krb5_prompt prompts[]);
 
 /**
- * @brief Prompt user for password.
+ * Prompt user for password.
+ *
+ * @param [in]     context      Library context
+ * @param          data         Unused (callback argument)
+ * @param [in]     name         Name to output during prompt
+ * @param [in]     banner       Banner to output during prompt
+ * @param [in]     num_prompts  Number of prompts in @a prompts
+ * @param [in,out] prompts      Array of output prompts and replies
  *
- * @param context           Context structure [input, output]
- * @param data              Unused
- * @param name              Name to output during prompt [input]
- * @param banner            Banner to output during prompt [input]
- * @param num_prompts       Number of prompts passed in @a prompts [input]
- * @param prompts           Array of krb5_prompt structures containing output prompts and replies [input, output]
+ * This function is intended to be used as a prompter callback for
+ * krb5_get_init_creds_password() or krb5_init_creds_init().
  *
- * Prompt the user for the  password associated with the given principal name,
- * and set the reply field of the @a prompts argument to the password input. The hidden
- * flag in the @c prompts structure controls whether the password input is echoed back
- * to the terminal.
+ * Writes @a name and @a banner to stdout, each followed by a newline, then
+ * writes each prompt field in the @a prompts array, followed by ": ", and sets
+ * the reply field of the entry to a line of input read from stdin.  If the
+ * hidden flag is set for a prompt, then terminal echoing is turned off when
+ * input is read.
  *
  * @retval
  *  0   Success
@@ -5622,13 +5686,16 @@ typedef struct _krb5_get_init_creds_opt {
 #define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS       0x0400
 
 
-/** Allocate a new extended krb5_get_init_creds_opt structure.
+/**
+ * Allocate a new initial credential options structure.
  *
- * @param [in,out] context  Context structure
- * @param [out]  opt  Pointer to @c _krb5_get_init_creds_opt structure to be allocated
+ * @param [in]  context         Library context
+ * @param [out] opt             New options structure
  *
- * The caller of this function must call krb5_get_init_creds_opt_free() to free @a opt
- * when it is no longer needed.
+ * This function is the preferred way to create an options structure for
+ * getting initial credentials, and is required to make use of certain options.
+ * Use krb5_get_init_creds_opt_free() to free @a opt when it is no longer
+ * needed.
  *
  * @retval 0 - Success; Kerberos errors otherwise.
  */
@@ -5636,10 +5703,11 @@ krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_alloc(krb5_context context,
                               krb5_get_init_creds_opt **opt);
 
-/** Free an extended krb5_get_init_creds_opt structure.
+/**
+ * Free initial credential options.
  *
- * @param      context   Context structure
- * @param [in] opt       Pointer to @c _krb5_get_init_creds_opt structure to be freed
+ * @param [in] context          Library context
+ * @param [in] opt              Options structure to free
  *
  * @sa krb5_get_init_creds_opt_alloc()
  */
@@ -5647,165 +5715,137 @@ void KRB5_CALLCONV
 krb5_get_init_creds_opt_free(krb5_context context,
                              krb5_get_init_creds_opt *opt);
 
-/** Initialize a krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt   Pointer to krb5_get_init_creds_opt structure to be initialized
- *
- * @warning Callers MUST NOT call krb5_get_init_creds_opt_init() after allocating an
- * krb5_get_init_creds_opt structure using krb5_get_init_creds_opt_alloc().
- * To do so will introduce memory leaks.
- *
- * Sets @a opt->flag to KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT
- */
+/** @deprecated Use krb5_get_init_creds_opt_alloc() instead. */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
 
-/** Initialize the ticket lifetime field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt           Options
- * @param [in]     tkt_life      Ticket lifetime
- *
- * Sets KRB5_GET_INIT_CREDS_OPT_TKT_LIFE flag in @a opt
+/**
+ * Set the ticket lifetime in initial credential options.
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt              Options structure
+ * @param [in] tkt_life         Ticket lifetime
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
                                      krb5_deltat tkt_life);
 
-/** Set the ticket renewal lifetime field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt               Pointer to @a options field
- * @param [in]     renew_life        Ticket renewal lifetime
- *
- * Sets KRB5_GET_INIT_CREDS_OPT_iRENEW_LIFE flag in @a opt
+/**
+ * Set the ticket renewal lifetime in initial credential options.
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt              Pointer to @a options field
+ * @param [in] renew_life       Ticket renewal lifetime
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
                                        krb5_deltat renew_life);
 
-/** Set the forwardable field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt          Options
- * @param [in]     forwardable  Flag indicating whether credentials are forwardable
+/**
+ * Set or unset the forwardable flag in initial credential options.
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_FORWARDABLE flag in @a opt
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt              Options structure
+ * @param [in] forwardable      Whether credentials should be forwardable
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
                                         int forwardable);
 
-/** Set the proxiable field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt           Options
- * @param [in]     proxiable     Flag indicating whether credentials are proxiable
+/**
+ * Set or unset the proxiable flag in initial credential options.
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_PROXYABLE flag in @a opt
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt              Options structure
+ * @param [in] proxiable        Whether credentials should be proxiable
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
                                       int proxiable);
 
-/** Set canonicalize flag in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt               Options
- * @param [in]     canonicalize      Boolean flag
- *
- * Sets KRB5_GET_INIT_CREDS_OPT_CANONICALIZE flag in @a opt
+/**
+ * Set or unset the canonicalize flag in initial credential options.
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt              Options structure
+ * @param [in] canonicalize     Whether to canonicalize client principal
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
                                          int canonicalize);
 
-/** Set an anonymous flag in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt               Options
- * @param [in]     anonymous         Boolean flag
- *
- * This function may be used to request anonymous credentials from the KDC
- * by setting @a anonymous to non-zero.
- *
- * Note that anonymous credentials are only a request; clients must verify that
- * credentials are anonymous if that is a requirement.
+/**
+ * Set or unset the anonymous flag in initial credential options.
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_ANONYMOUS flag in @a opt.
+ * @param [in] opt              Options structure
+ * @param [in] anonymous        Whether to make an anonymous request
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * This function may be used to request anonymous credentials from the KDC by
+ * setting @a anonymous to non-zero.  Note that anonymous credentials are only
+ * a request; clients must verify that credentials are anonymous if that is a
+ * requirement.
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
                                       int anonymous);
 
-/** Set an encryption list field in the krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt                    Options
- * @param [in]     etype_list             Pointer to the encryption type to set
- * @param [in]     etype_list_length      Length of the etype_list field
+/**
+ * Set allowable encryption types in initial credential options.
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * @param [in] opt               Options structure
+ * @param [in] etype_list        Array of encryption types
+ * @param [in] etype_list_length Length of @a etype_list
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
                                        krb5_enctype *etype_list,
                                        int etype_list_length);
 
-/** Set an address list field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt               Options
- * @param [in]     addresses         Addresses to be stored in the ticket
+/**
+ * Set address restrictions in initial credential options.
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST flag in @a opt
+ * @param [in] opt              Options structure
+ * @param [in] addresses        Null-terminated array of addresses
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
                                          krb5_address **addresses);
 
-/** Set the preauth_list field in krb5_get_init_creds_opt structure.
- *
- * @param [in,out] opt                    Options
- * @param [in]     preauth_list           Pointer to Pre-athentication type
- * @param [in]     preauth_list_length    Length of @a preauth_list field
+/**
+ * Set preauthentication types in initial credential options.
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST flag in @a opt
+ * @param [in] opt                 Options structure
+ * @param [in] preauth_list        Array of preauthentication types
+ * @param [in] preauth_list_length Length of @a preauth_list
  *
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * This function can be used to perform optimistic preauthentication when
+ * getting initial credentials, in combination with
+ * krb5_get_init_creds_opt_set_salt() and krb5_get_init_creds_opt_set_pa().
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
                                          krb5_preauthtype *preauth_list,
                                          int preauth_list_length);
 
-/** Set prompt for a salt field in krb5_get_init_creds_opt structure.
+/**
+ * Set salt for optimistic preauthentication in initial credential options.
  *
- * @param [in,out] opt          Options
- * @param [in]     salt         Salt data
+ * @param [in] opt              Options structure
+ * @param [in] salt             Salt data
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_SALT flag in @a opt.
+ * When getting initial credentials with a password, a salt string it used to
+ * convert the password to a key.  Normally this salt is obtained from the
+ * first KDC reply, but when performing optimistic preauthentication, the
+ * client may need to supply the salt string with this function.
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
                                  krb5_data *salt);
 
-/** Set prompt for a password flag in krb5_get_init_creds_opt structure.
+/**
+ * Set or unset change-password-prompt flag in initial credential options.
  *
- * @param [in,out] opt            Options
- * @param [in]     prompt         Boolean prompt to change password
+ * @param [in] opt              Options structure
+ * @param [in] prompt           Whether to prompt to change password
  *
- * Sets KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT flag in @a opt.
+ * This flag is on by default.  It controls whether
+ * krb5_get_init_creds_password() will react to an expired-password error by
+ * prompting for a new password and attempting to change the old one.
  */
 void KRB5_CALLCONV
 krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt,
@@ -5817,84 +5857,85 @@ typedef struct _krb5_gic_opt_pa_data {
     char *value;
 } krb5_gic_opt_pa_data;
 
-/** Feed preauth plugins with the given options.
+/**
+ * Supply options for preauthentication in initial credential options.
  *
- * @param [in,out] context           Context structure
- * @param [in]     opt               Pre options
- * @param [in]     attr              Pre attribute
- * @param [in]     value             Pre value
+ * @param [in] context          Library context
+ * @param [in] opt              Options structure
+ * @param [in] attr             Preauthentication option name
+ * @param [in] value            Preauthentication option value
  *
- * This function allows the caller to supply options to preauth
- * plugins.  Preauth plugin modules are given a chance to look
- * at each option at the time this function is called in order
- * to check the validity of the option.
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * This function allows the caller to supply options for preauthentication.
+ * The values of @a attr and @a value are supplied to each preauthentication
+ * module available within @a context.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_set_pa(krb5_context context,
                                krb5_get_init_creds_opt *opt, const char *attr,
                                const char *value);
 
-/** Set a location of FAST cache containing TGT based on cache name.
+/**
+ * Set location of FAST armor ccache in initial credential options.
  *
- * @param [in,out] context             Context structure
- * @param [in,out] opt                 Options
- * @param [in]     fast_ccache_name    Credential cache name
+ * @param [in] context          Library context
+ * @param [in] opt              Options
+ * @param [in] fast_ccache_name Credential cache name
  *
- * If the @a fast_ccache_name is set, then FAST may be
- * required by the client library. Starting from MIT Kerberos version 1.8
- * FAST is used if available; krb5_get_init_creds_opt_set_fast_flags()
- * may be used to require that the request fail is FAST is unavailable.
- * In version 1.7 setting the fast ccache at all required that FAST
- * be present or the request would fail.
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * Sets the location of a credential cache containing an armor ticket to
+ * protect an initial credential exchange using the FAST protocol extension.
+ *
+ * In version 1.7, setting an armor ccache requires that FAST be used for the
+ * exchange.  In version 1.8 or later, setting the armor ccache causes FAST to
+ * be used if the KDC supports it; krb5_get_init_creds_opt_set_fast_flags()
+ * must be used to require that FAST be used.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_set_fast_ccache_name(krb5_context context,
                                              krb5_get_init_creds_opt *opt,
                                              const char *fast_ccache_name);
 
-/** Set a location of FAST cache containing TGT based on krb5_ccache object.
+/**
+ * Set FAST armor cache in initial credential options.
  *
- * @param [in,out] context             Context structure
- * @param [in,out] opt                 Options
- * @param [in]     fast_ccache_name    Credential cache handle
+ * @param [in] context           Library context
+ * @param [in] opt               Options
+ * @param [in] ccache            Credential cache handle
  *
- * Set the FAST ccache name as in krb5_get_init_creds_opt_set_fast_ccache_name(),
- * but using a krb5_ccache rather than a name.
- * The @a opt pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
+ * This function is similar to krb5_get_init_creds_opt_set_fast_ccache_name(),
+ * but uses a credential cache handle instead of a name.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
                                         krb5_get_init_creds_opt *opt,
-                                        krb5_ccache fast_ccache_name);
+                                        krb5_ccache ccache);
 
-/** Set an output credentials cache in krb5_get_init_creds_opt structure.
+/**
+ * Set an output credential cache in initial credential options.
  *
- * @param [in,out] context       Context structure
- * @param [in,out] opt           Options
- * @param [in]     ccache        Credential cache to use
+ * @param [in] context          Library context
+ * @param [in] opt              Options
+ * @param [in] ccache           Credential cache handle
  *
- * If set, then the krb5_get_init_creds family of APIs will write out credentials
- * to the given ccache. Setting an output ccache is desirable both because it
- * simplifies calling code and because it permits the krb5_get_init_creds APIs
- * to write out configuration information about the realm to the ccache.
+ * If an output credential cache is set, then the krb5_get_init_creds family of
+ * APIs will write credentials to it.  Setting an output ccache is desirable
+ * both because it simplifies calling code and because it permits the
+ * krb5_get_init_creds APIs to write out configuration information about the
+ * realm to the ccache.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_set_out_ccache(krb5_context context,
                                        krb5_get_init_creds_opt *opt,
                                        krb5_ccache ccache);
 
-/** Store FAST flags in krb5_get_init_creds_opt structure.
+/**
+ * Set FAST flags in initial credential options.
  *
- * @param [in,out] context       Context structure
- * @param [in,out] opt           Options
- * @param [in]     flags         FAST flags (for example, KRB5_FAST_REQUIRED)
+ * @param [in] context          Library context
+ * @param [in] opt              Options
+ * @param [in] flags            FAST flags
  *
- * This function may be used to require that the request fail if FAST is unavailable.
+ * The following flag values are valid:
+ * @li @c KRB5_FAST_REQUIRED - Require FAST to be used
  *
  * @retval
  * 0 - Success; Kerberos errors otherwise.
@@ -5904,14 +5945,12 @@ krb5_get_init_creds_opt_set_fast_flags(krb5_context context,
                                        krb5_get_init_creds_opt *opt,
                                        krb5_flags flags);
 
-/** Obtain FAST flags from krb5_get_init_creds_opt structure.
- *
- * @param [in,out] context       Context structure
- * @param [in]     opt           Options
- * @param [out]    out_flags     FAST flags
+/**
+ * Retrieve FAST flags from initial credential options.
  *
- * Get FAST @a out_flags from @a opt
- * This function may be used to verify if KDC supports FAST.
+ * @param [in]  context         Library context
+ * @param [in]  opt             Options
+ * @param [out] out_flags       FAST flags
  *
  * @retval
  * 0 - Success; Kerberos errors otherwise.
@@ -5930,12 +5969,13 @@ typedef void
                                            krb5_timestamp account_expiration,
                                            krb5_boolean is_last_req);
 
-/** Set an expire callback in extended krb5_get_init_creds_opt structure.
+/**
+ * Set an expiration callback in initial credential options.
  *
- * @param [in,out] context       Context structure
- * @param [in,out] opt           Options structure
- * @param [in]     cb            Callback function
- * @param [in]     data          Data
+ * @param [in] context          Library context
+ * @param [in] opt              Options structure
+ * @param [in] cb               Callback function
+ * @param [in] data             Callback argument
  *
  * Set a callback to receive password and account expiration times.
  *
@@ -5972,20 +6012,24 @@ krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
                                             krb5_expire_callback_func cb,
                                             void *data);
 
-/** Get initial credentials using a password.
- *
- * @param [in]     context           Context structure
- * @param [in,out] creds             Credentials structure to be filled in
- * @param [in]     client            Client principal
- * @param [in]     password          Password associated with initial credentials
- * @param [in]     prompter          Pointer to password prompt routine
- * @param [in]     data              Data for password prompt routine
- * @param [in]     start_time        Time when a ticket should become valid; 0 means from now
- * @param [in]     in_tkt_service    Service name to use while getting initial credentials
- * @param [in]     k5_gic_options    Flags and options
- *
- * This function requests KDC for an initial credentials for @a client using
- * @a password.
+/**
+ * Get initial credentials using a password.
+ *
+ * @param [in]  context         Library context
+ * @param [out] creds           New credentials
+ * @param [in]  client          Client principal
+ * @param [in]  password        Password (or NULL)
+ * @param [in]  prompter        Prompter function
+ * @param [in]  data            Prompter callback data
+ * @param [in]  start_time      Time when ticket becomes valid (0 for now)
+ * @param [in]  in_tkt_service  Service name of initial credentials (or NULL)
+ * @param [in]  k5_gic_options  Initial credential options
+ *
+ * This function requests KDC for an initial credentials for @a client using @a
+ * password.  If @a password is NULL, a password will be prompted for using @a
+ * prompter if necessary.  If @a in_tkt_service is specified, it is parsed as a
+ * principal name (with the realm ignored) and used as the service principal
+ * for the request; otherwise the ticket-granting service is used.
  *
  * @sa krb5_verify_init_creds()
  *
@@ -6024,71 +6068,76 @@ typedef struct _krb5_init_creds_context *krb5_init_creds_context;
 
 #define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1  /* More responses needed */
 
-/** Free an initial credentials asynchronous context.
+/**
+ * Free an initial credentials context.
  *
- * @param [in] context      A krb5 library context
- * @param [in] ctx          Initial credentials context to free.
+ * @param [in] context          Library context
+ * @param [in] ctx              Initial credentials context
  */
 void KRB5_CALLCONV
 krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx);
 
-/** Acquire credentials asynchronously.
+/**
+ * Acquire credentials using an initial credentials context.
  *
- * @param [in]     context      A krb5 library context
- * @param [in,out] ctx          Initial credentials context
+ * @param [in] context          Library context
+ * @param [in] ctx              Initial credentials context
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * This function synchronously obtains credentials using a context created by
+ * krb5_init_creds_init().  On successful return, the credentials can be
+ * retrieved with krb5_init_creds_get_creds().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx);
 
-/** Copy the acquired initial credentials contents.
+/**
+ * Retrieve acquired credentials from an initial credentials context.
  *
- * @param [in]  context       A krb5 library context
- * @param [in]  ctx           Initial credentials context
- * @param [out] creds         Copy of @a ctx->cred
+ * @param [in]  context         Library context
+ * @param [in]  ctx             Initial credentials context
+ * @param [out] creds           Acquired credentials
  *
- * This function copies the acquired initial credentials from
- * @a ctx->cred into @a creds.
- * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
+ * This function copies the acquired initial credentials from @a ctx into @a
+ * creds, after the successful completion of krb5_init_creds_get() or
+ * krb5_init_creds_step().  Use krb5_free_cred_contents() to free @a creds when
+ * it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_get_creds(krb5_context context, krb5_init_creds_context ctx,
                           krb5_creds *creds);
 
-/** Get the last error data from KDC while acquiring initial credentials.
+/**
+ * Get the last error from KDC from an initial credentials context.
  *
- * @param [in]  context  A krb5 library context
- * @param [in]  ctx      Initial credentials context
- * @param [out] error    If non-null, contains error packet returned from KDC
+ * @param [in]  context         Library context
+ * @param [in]  ctx             Initial credentials context
+ * @param [out] error           Error from KDC, or NULL if none was received
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_get_error(krb5_context context, krb5_init_creds_context ctx,
                           krb5_error **error);
 
-/** Create a context for acquiring initial credentials.
+/**
+ * Create a context for acquiring initial credentials.
  *
- * @param [in]  context      A krb5 library context
- * @param [in]  client       Client principal to get initial credentials for.
- *                           If NULL - the default principal is used
- * @param [in]  prompter     Prompter
- * @param [in]  data         Prompter data
- * @param [in]  start_time   Time when credentials should become valid;
- *                           0 means from now
- * @param [in]  options      KRB5_GET_INIT_CREDS_OPT options for this request.
- *                           If NULL - the default options are used
- *                           (see krb5_get_init_creds_opt_init())
- * @param [out] ctx          A new initial credentials context.
+ * @param [in]  context         Library context
+ * @param [in]  client          Client principal to get initial creds for
+ * @param [in]  prompter        Prompter callback
+ * @param [in]  data            Prompter callback argument
+ * @param [in]  start_time      Time when credentials become valid (0 for now)
+ * @param [in]  options         Options structure (NULL for default)
+ * @param [out] ctx             New initial credentials context
  *
- * This function initializes a new context for acquiring initial credentials
- * asynchronously.
- * Use krb5_init_creds_free() to free @a ctx when it is no longer needed.
+ * This function creates a new context for acquiring initial credentials.  Use
+ * krb5_init_creds_free() to free @a ctx when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_init(krb5_context context, krb5_principal client,
@@ -6096,73 +6145,98 @@ krb5_init_creds_init(krb5_context context, krb5_principal client,
                      krb5_deltat start_time, krb5_get_init_creds_opt *options,
                      krb5_init_creds_context *ctx);
 
-/** Specify a keytab to use for acquiring initial credentials.
+/**
+ * Specify a keytab to use for acquiring initial credentials.
  *
- * @param [in]      context  A krb5 library context
- * @param [in,out]  ctx      Initial credentials context
- * @param [in]      keytab   Key table handle
+ * @param [in] context          Library context
+ * @param [in] ctx              Initial credentials context
+ * @param [in] keytab           Key table handle
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * This function supplies a keytab containing the client key for an initial
+ * credentials request.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_set_keytab(krb5_context context, krb5_init_creds_context ctx,
                            krb5_keytab keytab);
 
-/** Perform the next step of asynchronous initial credentials acquisition.
- *
- * @param [in]     context  A krb5 library context
- * @param [in,out] ctx      Initial credentials context
- * @param [in]     in       KDC response (empty on the first call)
- * @param [out]    out      Buffer to be sent by the caller to the KDC
- *                          for the indicated @a realm.
- * @param [out]    realm    The realm for which the next request should be sent
- * @param [out]    flags    Indicates whether more responses are needed
- *                          (see KRB5_INIT_CREDS_STEP_FLAG_CONTINUE )
- *
- * Once the credentials have been acquired, the @a out buffer is empty and
- * @a flags is set to 0. If the request should be retried with TCP,
- * KRB5KRB_ERR_RESPONSE_TOO_BIG is returned.
+/**
+ * Get the next KDC request for acquiring initial credentials.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  ctx             Initial credentials context
+ * @param [in]  in              KDC response (empty on the first call)
+ * @param [out] out             Next KDC request
+ * @param [out] realm           Realm for next KDC request
+ * @param [out] flags           Output flags
+ *
+ * This function constructs the next KDC request in an initial credential
+ * exchange, allowing the caller to control the transport of KDC requests and
+ * replies.  On the first call, @a in should be set to an empty buffer; on
+ * subsequent calls, it should be set to the KDC's reply to the previous
+ * request.
+ *
+ * If more requests are needed, @a flags will be set to @c
+ * KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a
+ * out.  If no more requests are needed, @a flags will not contain @c
+ * KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
+ *
+ * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
+ * transmit the next request using TCP rather than UDP.  If this function
+ * returns any other error, the initial credential exchange has failed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_step(krb5_context context, krb5_init_creds_context ctx,
                      krb5_data *in, krb5_data *out, krb5_data *realm,
                      unsigned int *flags);
 
-/** Set a password for acquiring initial credentials.
+/**
+ * Set a password for acquiring initial credentials.
  *
- * @param [in]      context       A krb5 library context
- * @param [in,out]  ctx           Initial credentials context
- * @param [in]      password      Password
+ * @param [in] context          Library context
+ * @param [in] ctx              Initial credentials context
+ * @param [in] password         Password
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * This function supplies a password to be used to construct the client key for
+ * an initial credentials request.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_set_password(krb5_context context, krb5_init_creds_context ctx,
                              const char *password);
 
-/** Specify a requested service for the initial credentials.
+/**
+ * Specify a service principal for acquiring initial credentials.
  *
- * @param [in]      context       A krb5 library context
- * @param [in,out]  ctx           Initial credentials context
- * @param [in]      service       Requested service
+ * @param [in] context          Library context
+ * @param [in] ctx              Initial credentials context
+ * @param [in] service          Service principal string
  *
- * The old @a ctx->in_tkt_service is overriden by the new @a service.
+ * This function supplies a service principal string to acquire initial
+ * credentials for instead of the default krbtgt service.  @a service is parsed
+ * as a principal name; any realm part is ignored.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_set_service(krb5_context context, krb5_init_creds_context ctx,
                             const char *service);
 
-/** Retrieve the ticket times from the initial credentials context.
+/**
+ * Retrieve ticket times from an initial credentials context.
  *
- * @param [in]  context       A krb5 library context
- * @param [in]  ctx           Initial credentials context
- * @param [out] times         Ticket times for the acquired credentials
+ * @param [in]  context         Library context
+ * @param [in]  ctx             Initial credentials context
+ * @param [out] times           Ticket times for acquired credentials
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * The initial credentials context must have completed obtaining credentials
+ * via either krb5_init_creds_get() or krb5_init_creds_step().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
@@ -6174,14 +6248,16 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
 /**
  * Create a context to get credentials from a KDC's Ticket Granting Service.
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ccache   A credentials cache containing the desired credentials
- *                      or a Ticket Granting Ticket (TGT) for the client realm.
- *                      TGT and service credentials may be stored into this
- *                      cache as they are acquired.
- * @param[in]  creds    Input credentials
- * @param[in]  options  KRB5_GC_* options for this request.
- * @param[out] ctx      The TGS acquisition context.
+ * @param[in]  context          Library context
+ * @param[in]  ccache           Credential cache handle
+ * @param[in]  creds            Input credentials
+ * @param[in]  options          KRB5_GC_* options for this request.
+ * @param[out] ctx              New TGS request context
+ *
+ * This function prepares to obtain credentials matching @a creds, either by
+ * retrieving them from @a ccache or by making requests to ticket-granting
+ * services beginning with a ticket-granting ticket for the client principal's
+ * realm.
  *
  * The resulting TGS acquisition context can be used asynchronously with
  * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get().  See also
@@ -6189,7 +6265,7 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
  *
  * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
@@ -6197,41 +6273,43 @@ krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
                     krb5_tkt_creds_context *ctx);
 
 /**
- * Synchronously obtain credentials within an acquisition context.
+ * Synchronously obtain credentials using a TGS request context.
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ * @param[in] context           Library context
+ * @param[in] ctx               TGS request context
  *
- * This function repeatedly generates requests, sends them to the appropriate
- * realms' KDCs, and processes the replies until credentials are available for
- * retrieval with krb5_tkt_creds_get_creds().
+ * This function synchronously obtains credentials using a context created by
+ * krb5_tkt_creds_init().  On successful return, the credentials can be
+ * retrieved with krb5_tkt_creds_get_creds().
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
 
 /**
- * Retrieve credentials from an acquisition context, filling in @a creds.
+ * Retrieve acquired credentials from a TGS request context.
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
- * @param[out] creds    The acquired credentials
+ * @param[in]  context          Library context
+ * @param[in]  ctx              TGS request context
+ * @param[out] creds            Acquired credentials
  *
- * The acquisition context must have completed obtaining credentials via either
- * krb5_tkt_creds_get() or krb5_tkt_creds_step().
+ * This function copies the acquired initial credentials from @a ctx into @a
+ * creds, after the successful completion of krb5_tkt_creds_get() or
+ * krb5_tkt_creds_step().  Use krb5_free_cred_contents() to free @a creds when
+ * it is no longer needed.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_creds *creds);
 
 /**
- * Release the resources used by an acquisition context.
+ * Free a TGS request context.
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ * @param[in]  context  Library context
+ * @param[in]  ctx      TGS request context
  */
 void KRB5_CALLCONV
 krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
@@ -6239,22 +6317,30 @@ krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
 #define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1  /* More responses needed. */
 
 /**
- * Process a response and generate the next request to acquire credentials.
+ * Get the next KDC request in a TGS exchange.
+ *
+ * @param[in]  context          Library context
+ * @param[in]  ctx              TGS request context
+ * @param[in]  in               KDC response (empty on the first call)
+ * @param[out] out              Next KDC request
+ * @param[out] realm            Realm for next KDC request
+ * @param[out] flags            Output flags
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
- * @param[in]  in       The last response (empty or NULL for first call)
- * @param[out] out      The next request to be sent
- * @param[out] realm    The realm to which the next request should be sent
- * @param[out] flags    Indicates whether more responses are needed
+ * This function constructs the next KDC request for a TGS exchange, allowing
+ * the caller to control the transport of KDC requests and replies.  On the
+ * first call, @a in should be set to an empty buffer; on subsequent calls, it
+ * should be set to the KDC's reply to the previous request.
  *
- * On the first call, @a in should be empty or NULL.  If more responses are
- * needed, the @a flags output parameter will contain @a
- * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.  In that case, the caller must transport
- * @a out to a KDC for @a realm and receive a response, which should be
- * provided as @a in to the next call.
+ * If more requests are needed, @a flags will be set to @c
+ * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a
+ * out.  If no more requests are needed, @a flags will not contain @c
+ * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
+ * transmit the next request using TCP rather than UDP.  If this function
+ * returns any other error, the TGS exchange has failed.
+ *
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
@@ -6262,33 +6348,37 @@ krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
                     unsigned int *flags);
 
 /**
- * Retrieve ticket times for obtained credentials, filling in @a times.
+ * Retrieve ticket times from a TGS request context.
  *
- * @param[in]  context  A krb5 library context (see krb5_init_context())
- * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
- * @param[out] times    Ticket times for the acquired credentials
+ * @param[in]  context          Library context
+ * @param[in]  ctx              TGS request context
+ * @param[out] times            Ticket times for acquired credentials
  *
- * The acquisition context must have completed obtaining credentials via either
+ * The TGS request context must have completed obtaining credentials via either
  * krb5_tkt_creds_get() or krb5_tkt_creds_step().
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_ticket_times *times);
 
-/** Get initial credentials using a key table.
- *
- * @param [in]  context           Context structure
- * @param [in,out] creds          Credentials structure to be filled in
- * @param [in]  client            Client principal to get initial credentials for
- * @param [in]  arg_keytab        Key table handle
- * @param [in]  start_time        Time when a ticket should become valid; 0 means from now
- * @param [in]  in_tkt_service    Service name to use while getting initial credentials
- * @param [in]  k5_gic_options    Flags and options
- *
- * This function requests initial credentials for @a client from KDC using a key
- * stored in @a arg_keytab, or from the default keytab if @a arg_keytab is NULL.
+/**
+ * Get initial credentials using a key table.
+ *
+ * @param [in]  context         Library context
+ * @param [out] creds           New credentials
+ * @param [in]  client          Client principal
+ * @param [in]  arg_keytab      Key table handle
+ * @param [in]  start_time      Time when ticket becomes valid (0 for now)
+ * @param [in]  in_tkt_service  Service name of initial credentials (or NLUL)
+ * @param [in]  k5_gic_options  Initial credential options
+ *
+ * This function requests KDC for an initial credentials for @a client using a
+ * client key stored in @a arg_keytab.  If @a in_tkt_service is specified, it
+ * is parsed as a principal name (with the realm ignored) and used as the
+ * service principal for the request; otherwise the ticket-granting service is
+ * used.
  *
  * @sa krb5_verify_init_creds()
  *
@@ -6310,69 +6400,84 @@ typedef struct _krb5_verify_init_creds_opt {
 
 #define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL        0x0001
 
-/** Initialize a @a flags field in krb5_verify_init_creds_opt structure.
- *
- * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure
+/**
+ * Initialize a credential verification options structure.
  *
- * Sets @a k5_vic_options flags fiels to zero.
+ * @param [in] k5_vic_options   Verification options structure
  */
 void KRB5_CALLCONV
 krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options);
 
-/** Set a @a ap_req_nofail field in krb5_verify_init_creds_opt structure.
+/**
+ * Set whether credential verification is required.
  *
- * @param [out] k5_vic_options  Pointer to krb5_verify_init_creds_opt structure
- * @param [in]  ap_req_nofail   Boolean value to set for the ap_req_nofail field
+ * @param [in] k5_vic_options   Verification options structure
+ * @param [in] ap_req_nofail    Whether to require successful verification
  *
- * This function sets KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL flag and
- * ap_req_nofail field to @a ap_req_nofail in @a k5_vic_options.
- * If @a ap_req_nofail is FALSE and keytab is missing (empty or unreadable),
- * krb5_verify_init_creds() will succeed even though verification cannot be
- * performed.
- * This function may be used to override the krb5 configuration setting for
- * verify_ap_req_nofail attribute.
+ * This function determines how krb5_verify_init_creds() behaves if no keytab
+ * information is available.  If @a ap_req_nofail is @c FALSE, verification
+ * will be skipped in this case and krb5_verify_init_creds() will return
+ * successfully.  If @a ap_req_nofail is @c TRUE, krb5_verify_init_creds() will
+ * not return successfully unless verification can be performed.
+ *
+ * If this function is not used, the behavior of krb5_verify_init_creds() is
+ * determined through configuration.
  */
 void KRB5_CALLCONV
 krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options,
                                              int ap_req_nofail);
 
-/** Verify initial credentials and store them in the credentials cache.
+/**
+ * Verify initial credentials against a keytab.
  *
- * @param [in]  context        Context structure
- * @param [in]  creds          Initial credentials to be verified
- * @param [in]  server_arg     Server principal;
- *                             if NULL - use a principal name from @a keytab_arg
- * @param [in]  keytab_arg     Key table to verify @a creds against
- * @param [out] ccache_arg     Credentials cache to store all fetched from KDC credentials
- *                             if NULL - memory credential will be used and then destroyed.
- * @param [in]  options        Pointer to krb5_verify_init_creds_opt structure
+ * @param [in]     context      Library context
+ * @param [in]     creds        Initial credentials to be verified
+ * @param [in]     server_arg   Server principal (or NULL)
+ * @param [in]     keytab_arg   Key table (NULL to use default keytab)
+ * @param [in,out] ccache_arg   Credential cache for fetched creds (or NULL)
+ * @param [in]     options      Verification options (NULL for default options)
  *
+ * This function attempts to verify that @a creds were obtained from a KDC with
+ * knowledge of a key in @a keytab_arg.  If @a server_arg is provided, the
+ * highest-kvno key entry for that principal name is used to verify the
+ * credentials; otherwise, the highest-kvno key entry for the first principal
+ * listed in @a keytab_arg is used.
  *
- * @sa krb5_verify_init_creds_opt_set_ap_req_nofail() and
- *     krb5_verify_init_creds_opt_init()
+ * If the specified keytab does not exist, or is empty, or cannot be read, or
+ * does not contain an entry for @a server_arg, then credential verification
+ * may be skipped unless configuration demands that it succeed.  The caller can
+ * control this behavior by providing a verification options structure; see
+ * krb5_verify_init_creds_opt_init() and
+ * krb5_verify_init_creds_opt_set_ap_req_nofail().
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * If @a ccache_arg is NULL, any additional credentials fetched during the
+ * verification process will be destroyed.  If @a ccache_arg points to NULL, a
+ * memory ccache will be created for the additional credentials and returned in
+ * @a ccache_arg.  If @a ccache_arg points to a valid credential cache handle,
+ * the additional credentials will be stored in that cache.
+ *
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_verify_init_creds(krb5_context context, krb5_creds *creds,
                        krb5_principal server_arg, krb5_keytab keytab_arg,
                        krb5_ccache *ccache_arg, krb5_verify_init_creds_opt *options);
 
-/** Get validated credentials from the KDC.
+/**
+ * Get validated credentials from the KDC.
+ *
+ * @param [in]  context         Library context
+ * @param [out] creds           Validated credentials
+ * @param [in]  client          Client principal name
+ * @param [in]  ccache          Credential cache
+ * @param [in]  in_tkt_service  Server principal string (or NULL)
  *
- * @param [in,out] context           Context structure
- * @param [out]    creds             Credential structure to fill in
- * @param [in]     client            Client principal name
- * @param [in]     ccache            Credentials cache
- * @param [in]     in_tkt_service    Principal name of requesting server
+ * This function gets a validated credential using a postdated credential from
+ * @a ccache.  If @a in_tkt_service is specified, it is parsed (with the realm
+ * part ignored) and used as the server principal of the credential;
+ * otherwise, the ticket-granting service is used.
  *
- * This function gets a validated single service ticket, that is specified as
- * @a in_tkt_service parameter, from KDC.
- * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
- * old existing credentials from @a ccache so they can be used to get a validated
- * credential from KDC.
- * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
- * The result is placed in @a creds.
+ * If successful, the validated credential is placed in @a creds.
  *
  * @sa krb5_get_renewed_creds()
  *
@@ -6396,23 +6501,21 @@ krb5_get_validated_creds(krb5_context context, krb5_creds *creds,
                          krb5_principal client, krb5_ccache ccache,
                          char *in_tkt_service);
 
-/** Get renewed credential from KDC using the existing one.
+/**
+ * Get renewed credential from KDC using an existing credential.
  *
- * @param [in,out] context           Context structure
- * @param [out]    creds             Credentials structure to fill in
- * @param [in]     client            Client principal name
- * @param [in]     ccache            Credentials cache
- * @param [in]     in_tkt_service    Principal name of requesting server
+ * @param [in]  context         Library context
+ * @param [out] creds           Renewed credentials
+ * @param [in]  client          Client principal name
+ * @param [in]  ccache          Credential cache
+ * @param [in]  in_tkt_service  Server principal string (or NULL)
  *
- * This function gets a renewed single service ticket, that is specified as
- * @a in_tkt_service parameter, from KDC.
- * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
- * old existing credentials from @a ccache so they can be used to get a new
- * credential from KDC.
- * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
- * The result is placed in @a creds.
+ * This function gets a renewed credential using an existing one from @a
+ * ccache.  If @a in_tkt_service is specified, it is parsed (with the realm
+ * part ignored) and used as the server principal of the credential; otherwise,
+ * the ticket-granting service is used.
  *
- * @sa krb5_get_validated_creds()
+ * If successful, the renewed credential is placed in @a creds.
  *
  * @retval
  * 0 Success
@@ -6424,24 +6527,26 @@ krb5_get_renewed_creds(krb5_context context, krb5_creds *creds,
                        krb5_principal client, krb5_ccache ccache,
                        char *in_tkt_service);
 
-/** Decode a formatted ticket.
+/**
+ * Decode an ASN.1-formatted ticket.
  *
- * @param [in]  code          Formatted ticket
- * @param [out] rep           Decoded ticket information
+ * @param [in]  code            ASN.1-formatted ticket
+ * @param [out] rep             Decoded ticket information
  *
- * @retval 0  Success; Otherwise - Kerberos error codes
+ * @retval 0  Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep);
 
-/** Retrieve an attribute value from @a appdefaults section of krb5.conf.
+/**
+ * Retrieve a string value from the appdefaults section of krb5.conf.
  *
- * @param [in]  context           Context structure
- * @param [in]  appname           Application name
- * @param [in]  realm             Realm name
- * @param [in]  option            Option to be checked
- * @param [in]  default_value     Default Boolean value to return if no match is found
- * @param [out] ret_value         String value of @a option
+ * @param [in]  context         Library context
+ * @param [in]  appname         Application name
+ * @param [in]  realm           Realm name
+ * @param [in]  option          Option to be checked
+ * @param [in]  default_value   Default value to return if no match is found
+ * @param [out] ret_value       String value of @a option
  *
  * This function gets the application defaults for @a option based on the given
  * @a appname and/or @a realm.
@@ -6453,14 +6558,15 @@ krb5_appdefault_string(krb5_context context, const char *appname,
                        const krb5_data *realm, const char *option,
                        const char *default_value, char ** ret_value);
 
-/** Retrieve a booloean attribute value from @a appdefaults section of krb5.conf.
+/**
+ * Retrieve a boolean value from the appdefaults section of krb5.conf.
  *
- * @param [in]  context           Context structure
- * @param [in]  appname           Application name
- * @param [in]  realm             Realm name
- * @param [in]  option            Option to be checked
- * @param [in]  default_value     Default Boolean value to return if no match is found
- * @param [out] ret_value         Boolean value of @a option
+ * @param [in]  context         Library context
+ * @param [in]  appname         Application name
+ * @param [in]  realm           Realm name
+ * @param [in]  option          Option to be checked
+ * @param [in]  default_value   Default value to return if no match is found
+ * @param [out] ret_value       Boolean value of @a option
  *
  * This function gets the application defaults for @a option based on the given
  * @a appname and/or @a realm.
@@ -6483,28 +6589,30 @@ krb5_appdefault_boolean(krb5_context context, const char *appname,
 
 typedef krb5_int32 krb5_prompt_type;
 
-/** Get @a prompt_types field from a context.
+/**
+ * Get prompt types array from a context.
  *
- * @param [in] context           Context structure
+ * @param [in] context          Library context
  *
  * @return
- * Pointer to the @a krb5_prompt_type field, which contains one
- * of the following values:
- *  @li  @c KRB5_PROMPT_TYPE_PASSWORD
- *  @li  @c KRB5_PROMPT_TYPE_NEW_PASSWORD
- *  @li  @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
- *  @li  @c KRB5_PROMPT_TYPE_PREAUTH
+ * Pointer to an array of prompt types corresponding to the prompter's @a
+ * prompts arguments.  Each type has one of the following values:
+ *  @li @c KRB5_PROMPT_TYPE_PASSWORD
+ *  @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD
+ *  @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
+ *  @li @c KRB5_PROMPT_TYPE_PREAUTH
 */
 krb5_prompt_type* KRB5_CALLCONV
 krb5_get_prompt_types(krb5_context context);
 
 /* Error reporting */
-/** Set error message state in a context structure.
+/**
+ * Set an extended error message for an error code.
  *
- * @param [in,out] ctx           Context structure
- * @param [in]     code          Error code
- * @param [in]     fmt           Error string for the error code
- * @param [in]     ...           printf(3) style parameters
+ * @param [in] ctx              Library context
+ * @param [in] code             Error code
+ * @param [in] fmt              Error string for the error code
+ * @param [in] ...              printf(3) style parameters
  */
 void KRB5_CALLCONV_C
 krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, ...)
@@ -6513,12 +6621,13 @@ krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt,
 #endif
     ;
 
-/** Set error message state in a context structure using a precomputed va_list.
+/**
+ * Set an extended error message for an error code using a va_list.
  *
- * @param [in,out] ctx           Context structure
- * @param [in]     code          Error code
- * @param [in]     fmt           Error string for the error code
- * @param [in]     args          @c va_list of arguments
+ * @param [in] ctx              Library context
+ * @param [in] code             Error code
+ * @param [in] fmt              Error string for the error code
+ * @param [in] args             List of vprintf(3) style arguments
  */
 void KRB5_CALLCONV
 krb5_vset_error_message(krb5_context  ctx, krb5_error_code code,
@@ -6528,26 +6637,28 @@ krb5_vset_error_message(krb5_context  ctx, krb5_error_code code,
 #endif
     ;
 
-/** Set the error message state of dest_ctx to that of src_ctx.
+/**
+ * Copy the most recent extended error message from one context to another.
  *
- * @param [in] dest_ctx    Context structure where the error message state is copied to
- * @param [in] src_ctx     Context structure where the error message state is copied from
+ * @param [in] dest_ctx         Library context to copy message to
+ * @param [in] src_ctx          Library context with current message
  */
 void KRB5_CALLCONV
 krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);
 
-/** Get error message state specific to the context.
+/**
+ * Get the (possibly extended) error message for a code.
  *
- * @param [in] ctx           Context structure
- * @param [in] code          Error code
+ * @param [in] ctx              Library context
+ * @param [in] code             Error code
  *
- * The behavior of krb5_get_error_message() is only defined the first
- * time it is called after a failed call to a krb5 function using the
- * same context, and only when the error code passed in is the same as
- * that returned by the krb5 function.
+ * The behavior of krb5_get_error_message() is only defined the first time it
+ * is called after a failed call to a krb5 function using the same context, and
+ * only when the error code passed in is the same as that returned by the krb5
+ * function.
  *
- * This function never returns NULL, so its result may be used
- * unconditionally as a C string.
+ * This function never returns NULL, so its result may be used unconditionally
+ * as a C string.
  *
  * The string returned by this function must be freed using
  * krb5_free_error_message()
@@ -6558,19 +6669,22 @@ krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);
 const char * KRB5_CALLCONV
 krb5_get_error_message(krb5_context ctx, krb5_error_code code);
 
-/** Free an error message state generated by krb5_get_error_message.
+/**
+ * Free an error message generated by krb5_get_error_message().
  *
- * @param [in] ctx           Context structure
- * @param [in] msg           Pointer to error message
+ * @param [in] ctx              Library context
+ * @param [in] msg              Pointer to error message
  */
 void KRB5_CALLCONV
 krb5_free_error_message(krb5_context ctx, const char *msg);
 
-/** Clear the error message state.
+/**
+ * Clear the extended error message in a context.
  *
- * @param [in,out] ctx           Context structure
+ * @param [in] ctx              Library context
  *
- * Similar to krb5_free_error_message() but @a ctx->msg is set to NULL.
+ * This function unsets the extended error message in a context, to ensure that
+ * it is not mistakenly applied to another occurrence of the same error code.
  */
 void KRB5_CALLCONV
 krb5_clear_error_message(krb5_context ctx);
@@ -6590,17 +6704,18 @@ krb5_encode_authdata_container(krb5_context context,
 /*
  * AD-KDCIssued
  */
-/** This function both encodes and signs AD-KDCIssued authorization data.
+/**
+ * Encode and sign AD-KDCIssued authorization data.
  *
- * @param [in] context        Context structure
- * @param [in] key            Session key
- * @param [in] issuer         The name of the issuing principal
- * @param [in] authdata       Authorization data to be signed
- * @param [out] ad_kdcissued  Authorization data to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  key             Session key
+ * @param [in]  issuer          The name of the issuing principal
+ * @param [in]  authdata        List of authorization data to be signed
+ * @param [out] ad_kdcissued    List containing AD-KDCIssued authdata
  *
- * This function both encodes and signs AD-KDCIssued authorization data @a authdata
- * (RFC 4120 section 5.2.6.2). A set of authorization data @a ad_kdcissued containing
- * a single AD-KDCIssued element is returned to the caller.
+ * This function wraps a list of authorization data entries @a authdata in an
+ * AD-KDCIssued container (see RFC 4120 section 5.2.6.2) signed with @a key.
+ * The result is returned in @a ad_kdcissued as a single-element list.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_make_authdata_kdc_issued(krb5_context context,
@@ -6609,17 +6724,19 @@ krb5_make_authdata_kdc_issued(krb5_context context,
                               krb5_authdata *const *authdata,
                               krb5_authdata ***ad_kdcissued);
 
-/** Decode and verify AD-KDCIssued authorization data.
+/**
+ * Unwrap and verify AD-KDCIssued authorization data.
  *
- * @param [in] context      Context structure
- * @param [in] key          Session key
- * @param [in] ad_kdcissued KDC issued authorization data to be verified
- * @param [out] issuer      The name of the issuing principal to be filled in (optional)
- * @param [out] authdata    Authorization data to be filled in
+ * @param [in] context          Library context
+ * @param [in] key              Session key
+ * @param [in] ad_kdcissued     AD-KDCIssued authorization data to be unwrapped
+ * @param [out] issuer          Name of issuing principal (or NULL)
+ * @param [out] authdata        Unwrapped list of authorization data
  *
- * This function both decodes and verifies AD-KDCIssued authorization data @a ad_kdcissued
- * (RFC 4120 section 5.2.6.2). The @a issuer and unwrapped authorization data @a authdata
- * are returned to the caller.
+ * This function unwraps an AD-KDCIssued authdatum (see RFC 4120 section
+ * 5.2.6.2) and verifies its signature against @a key.  The issuer field of the
+ * authdatum element is returned in @a issuer, and the unwrapped list of
+ * authdata is returned in @a authdata.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_verify_authdata_kdc_issued(krb5_context context,
@@ -6646,15 +6763,16 @@ krb5_verify_authdata_kdc_issued(krb5_context context,
 struct krb5_pac_data;
 typedef struct krb5_pac_data *krb5_pac;
 
-/** Add a buffer to the provided PAC and update header.
+/**
+ * Add a buffer to a PAC handle.
  *
- * @param [in]     context         Context structure
- * @param [in,out] pac             PAC handle
- * @param [in]     type            Type of data contained in @a data
- * @param [in]     data            Buffer to add
+ * @param [in] context          Library context
+ * @param [in] pac              PAC handle
+ * @param [in] type             Buffer type
+ * @param [in] data             contents
  *
- * This function adds a new @a data to @a pac if there isn't already a buffer
- * of this type in @a pac.
+ * This function adds a buffer of type @a type and contents @a data to @a pac
+ * if there isn't already a buffer of this type present.
  *
  * The valid values of @a type is one of the following:
  * @li @c PAC_LOGON_INFO         -  Logon information
@@ -6665,115 +6783,121 @@ typedef struct krb5_pac_data *krb5_pac;
  * @li @c PAC_DELEGATION_INFO    -  Constrained delegation information
  * @li @c PAC_UPN_DNS_INFO       -  User principal name and DNS information
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
                     const krb5_data *data);
 
-/** Free the storage assigned to a PAC.
+/**
+ * Free a PAC handle.
  *
- * @param      context         Context structure
+ * @param [in] context         Library context
  * @param [in] pac             PAC to be freed
  *
- * This function zeros out and frees the content of a @a pac and then
- * releases @a pac itself.
+ * This function frees the contents of @a pac and the structure itself.
  */
 void KRB5_CALLCONV
 krb5_pac_free(krb5_context context, krb5_pac pac);
 
-/** Find a buffer in a PAC and copy data into output buffer.
+/**
+ * Retrieve a buffer value from a PAC.
  *
- * @param [in]     context     Context structure
- * @param [in]     pac         PAC handle
- * @param [in]     type        Type of the buffer to be copied
- * @param [out]    data        Copy of a buffer to be filled in
+ * @param [in]  context         Library context
+ * @param [in]  pac             PAC handle
+ * @param [in]  type            Type of buffer to retrieve
+ * @param [out] data            Buffer value
  *
  * Use krb5_free_data_contents() to free @a data when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
                     krb5_data *data);
 
-/** Return an array of the types of data in the PAC.
- *
- * @param [in]     context         Context structure
- * @param [in,out] pac             PAC handle
- * @param [out]    len             Number of entries in the @a types array.
- * @param [out]    types           If non-null, contains an array of types
+/**
+ * Return an array of buffer types in a PAC handle.
  *
- * Free @a types when it is no linger needed.
+ * @param [in]  context         Library context
+ * @param [in]  pac             PAC handle
+ * @param [out] len             Number of entries in @a types
+ * @param [out] types           Array of buffer types
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len,
                    krb5_ui_4 **types);
 
-/** Create and initialize Privilege Attribute Certificate (PAC).
+/**
+ * Create an empty Privilege Attribute Certificate (PAC) handle.
  *
- * @param [in]  context         Context structure
- * @param [out] pac             PAC handle
+ * @param [in]  context         Library context
+ * @param [out] pac             New PAC handle
  *
  * Use krb5_pac_free() to free @a pac when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_init(krb5_context context, krb5_pac *pac);
 
-/** Parse the supplied data into the newly allocated PAC.
+/**
+ * Unparse an encoded PAC into a new handle.
  *
- * @param [in]  context         Context structure
+ * @param [in]  context         Library context
  * @param [in]  ptr             PAC buffer
- * @param [in]  len             Size of @a ptr
+ * @param [in]  len             Length of @a ptr
  * @param [out] pac             PAC handle
  *
  * Use krb5_pac_free() to free @a pac when it is no longer needed.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_parse(krb5_context context, const void *ptr, size_t len,
                krb5_pac *pac);
 
-/** Verify a PAC.
+/**
+ * Verify a PAC.
  *
- * @param [in] context         Context structure
- * @param [in] pac             PAC handle
- * @param [in] authtime        Timestamp to be compared with one in @a pac
- * @param [in] principal       If non-null, use it to validate PAC's client name
- *                             and ticket information.
- * @param [in] server          Compare it with PAC'c server checksum.
- *                             Must not be NULL.
- * @param [in] privsvr         If non-null, compare it with PAC'c KDC checksum
+ * @param [in] context          Library context
+ * @param [in] pac              PAC handle
+ * @param [in] authtime         Expected timestamp
+ * @param [in] principal        Expected principal name (or NULL)
+ * @param [in] server           Key to validate server checksum
+ * @param [in] privsvr          Key to validate KDC checksum (or NULL)
  *
  * This function validates @a pac against the supplied @a server, @a privsvr,
- * @a principal and @a authtime and then, if successful, sets @a pac->verified
- * to TRUE.
+ * @a principal and @a authtime.  If @a principal is NULL, the principal and
+ * authtime are not verified.  If @a privsvr is NULL, the KDC checksum is not
+ * verified.
+ *
+ * If successful, @a pac is marked as verified.
  *
  * @note A checksum mismatch can occur if the PAC was copied from a cross-realm
- * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of 10.6)
- * generates PACs with no server checksum at all. One should consider not failing
- * the whole authentication because of this reason, but, instead, marking PAC
- * as not verified.
+ * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of
+ * 10.6) generates PACs with no server checksum at all.  One should consider
+ * not failing the whole authentication because of this reason, but, instead,
+ * treating the ticket as if it did not contain a PAC or marking the PAC
+ * information as non-verified.
  *
- * @retval 0 Success; Otherwise - Kerberos error codes
+ * @retval 0 Success; otherwise - Kerberos error codes
  */
 krb5_error_code KRB5_CALLCONV
 krb5_pac_verify(krb5_context context, const krb5_pac pac,
                 krb5_timestamp authtime, krb5_const_principal principal,
                 const krb5_keyblock *server, const krb5_keyblock *privsvr);
 
-/** Allow the appplication to override the profile's allow_weak_crypto setting.
+/**
+ * Allow the appplication to override the profile's allow_weak_crypto setting.
  *
- * @param [in,out] context      Context structure
- * @param [in]     enable       Boolean flag
+ * @param [in] context          Library context
+ * @param [in] enable           Boolean flag
  *
- * This function sets @a allow_weak_crypto field in @a context to @a enable.
- * It is primarily for use by aklog.
+ * This function allows an application to override the allow_weak_crypto
+ * setting.  It is primarily for use by aklog.
  *
  * @retval 0  (always)
  */
@@ -6790,18 +6914,19 @@ typedef void
                                      const struct krb5_trace_info *info,
                                      void *cb_data);
 
-/** Specify a callback function for trace events.
+/**
+ * Specify a callback function for trace events.
  *
- * @param [in,out] context      Context structure
- * @param [in]     fn           Callback function name
- * @param [in]     cb_data      Callback data
+ * @param [in] context          Library context
+ * @param [in] fn               Callback function
+ * @param [in] cb_data          Callback data
  *
  * Specify a callback for trace events occurring in krb5 operations performed
  * within @a context.  @a fn will be invoked with @a context as the first
  * argument, @a cb_data as the last argument, and a pointer to a struct
  * krb5_trace_info as the second argument.  If the trace callback is reset via
  * this function or @a context is destroyed, @a fn will be invoked with a NULL
- * second argument to allow cleanup of @a cb_data.  Supply a NULL value for @a
+ * second argument so it can clean up @a cb_data.  Supply a NULL value for @a
  * fn to disable trace callbacks within @a context.
  *
  * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
@@ -6811,15 +6936,16 @@ krb5_error_code KRB5_CALLCONV
 krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
                         void *cb_data);
 
-/** Specify a file name for directing trace events.
+/**
+ * Specify a file name for directing trace events.
  *
- * @param [in,out] context      Context structure
- * @param [in]     filename     File name
+ * @param [in] context          Library context
+ * @param [in] filename         File name
  *
  * Open @a filename for appending (creating it, if necessary) and set up a
  * callback to write trace events to it.
  *
- * @return  KRB5_TRACE_NOSUPP if tracing is not supported in the library.
+ * @retval KRB5_TRACE_NOSUPP Tracing is not supported in the library.
  */
 krb5_error_code KRB5_CALLCONV
 krb5_set_trace_filename(krb5_context context, const char *filename);