Move doxygen comments from source to header. Updated comments and added some usage examples.

Affected functions: krb5_cc_get_config, krb5_cc_set_config, krb5_is_config_principal

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

1 files changed, 53 insertions, 4 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 011fbce3b..244e4629e 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -3938,29 +3938,78 @@ krb5_cc_default(krb5_context context, krb5_ccache *ccache);
 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.
+ *
+ * @param context        a Keberos context [input]
+ * @param id             the credential cache to store the data for [input]
+ * @param principal      configuration for a specific principal, if NULL, global for the whole cache.[input]
+ * @param key            name under which the configuraion is stored [input]
+ * @param data           data to be fetched; free with krb5_free_data_contents() [input,output]
+ *
+ * @code
+ *   krb5_data config_data;
+ *   config_data.data = NULL;
+ *   krb5_cc_get_config(context, ccache, target_principal, key, &config_data);
+ *   ...
+ *   krb5_free_data_contents(context, &config_data);
+ * @endcode
+ *
+ * @retval
+ * 0  Success
+ * @return
+ * Kerberos error codes
+ */
 krb5_error_code KRB5_CALLCONV
 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.
+ *
+ * @param context         a Keberos context [input,output]
+ * @param id              the credential cache to store the data for. [input]
+ * @param principal       configuration for a specific principal; if NULL, global for the whole cache.[input]
+ * @param key             name under which the configuraion is stored.[input]
+ * @param data            data to store. [input]
+ *
+ * @note Existing configuration under the same key is over-written.
+ *
+ * @code
+ *   config_data.data = "yes";
+ *   config_data.length = strlen(config_data.data);
+ *   krb5_cc_set_config(context, id, principal,key, &config_data);
+ * @endcode
+ *
+ * @retval
+ * 0  Success
+ * @return
+ * Kerberos error codes
+ */
 krb5_error_code KRB5_CALLCONV
 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.
+ *
+ * @param context        a Keberos context [input]
+ * @param principal      principal to check if it a configuration principal [input]
+ *
+ * @return Return TRUE (non zero) if the principal is a configuration
+ *        principal (generated part of krb5_cc_set_config()). Returns
+ *        FALSE (zero) if not a configuration principal.
+ */
 krb5_boolean KRB5_CALLCONV
 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
 
 /* krb5_free.c */
-/**
- * @brief Free a principal structure.
+/** Free a principal structure.
  *
  * @param context           Context structure [input, output]
- * @param val               Pointer to data structure to be freed [input, output]
+ * @param val               Pointer to data structure to be freed [input,output]
  *
  * @return
  * None
- *
  */
 void KRB5_CALLCONV
 krb5_free_principal(krb5_context context, krb5_principal val);