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

2 files changed, 55 insertions, 46 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);
diff --git a/src/lib/krb5/ccache/ccfns.c b/src/lib/krb5/ccache/ccfns.c
index 0a23738da..7d294e155 100644
--- a/src/lib/krb5/ccache/ccfns.c
+++ b/src/lib/krb5/ccache/ccfns.c
@@ -1,5 +1,5 @@
 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
-/* lib/krb5/ccache/ccfns.c */
+/* lib/krb5/ccache/ccfns.c - Dispatch methods for credentials cache code.*/
 /*
  * Copyright 2000, 2007, 2008  by the Massachusetts Institute of Technology.
  * All Rights Reserved.
@@ -24,10 +24,6 @@
  * or implied warranty.
  */
 
-/*
- * Dispatch methods for credentials cache code.
- */
-
 #include "k5-int.h"
 
 const char * KRB5_CALLCONV
@@ -226,7 +222,7 @@ build_conf_principals (krb5_context context, krb5_ccache id,
     ret = krb5_build_principal(context, &cred->server,
                                sizeof(conf_realm) - 1, conf_realm,
                                conf_name, name, pname, (char *)NULL);
-    free(pname);
+    krb5_free_unparsed_name(context, pname);
     if (ret) {
         krb5_free_principal(context, client);
         return ret;
@@ -236,16 +232,6 @@ build_conf_principals (krb5_context context, krb5_ccache id,
     return ret;
 }
 
-/*!
- * \param context a Keberos context
- * \param principal principal to check if it a configuration principal
- *
- * \brief 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)
@@ -266,20 +252,6 @@ krb5_is_config_principal (krb5_context context,
     return TRUE;
 }
 
-/*!
- * \param context a Keberos context
- * \param id the credential cache to store the data for
- * \param principal configuration for a specific principal, if
- * NULL, global for the whole cache.
- * \param key name under which the configuraion is stored.
- * \param data data to store
- *
- * \brief Store some configuration for the credential cache in the
- *        cache.  Existing configuration under the same key is
- *        over-written.
- *
- */
-
 krb5_error_code KRB5_CALLCONV
 krb5_cc_set_config (krb5_context context, krb5_ccache id,
                     krb5_const_principal principal,
@@ -310,18 +282,6 @@ out:
     return ret;
 }
 
-/*!
- * \param context a Keberos context
- * \param id the credential cache to store the data for
- * \param principal configuration for a specific principal, if
- *        NULL, global for the whole cache.
- * \param key name under which the configuraion is stored.
- * \param data data to fetched, free with krb5_data_free()
- *
- * \brief Get some configuration for the credential cache in the cache.
- */
-
-
 krb5_error_code KRB5_CALLCONV
 krb5_cc_get_config (krb5_context context, krb5_ccache id,
                     krb5_const_principal principal,