Updated documentation to reflect new APIs and re-ran Doxygen

ticket: 6055

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

9 files changed, 84 insertions, 43 deletions

diff --git a/src/include/kim/kim.h b/src/include/kim/kim.h
index 19e82ecb6..050e01b03 100644
--- a/src/include/kim/kim.h
+++ b/src/include/kim/kim.h
@@ -141,10 +141,6 @@ extern "C" {
  * - \subpage kim_options_overview
  * - \subpage kim_options_reference
  * 
- * <B>KIM Realms List (kim_favorite_identities_t)</B> views and edits the current user's favorite realms list:
- * - \subpage kim_favorite_identities_overview
- * - \subpage kim_favorite_identities_reference
- *
  * <B>KIM Preferences (kim_preferences_t)</B> views and edits the current user's preferences:
  * - \subpage kim_preferences_overview
  * - \subpage kim_preferences_reference
@@ -159,9 +155,6 @@ extern "C" {
  * - \subpage kim_string_overview
  * - \subpage kim_string_reference
  *
- * <B>KIM Error (kim_error_t)</B> provides a machine and user-readable error message:
- * - \subpage kim_error_overview
- * - \subpage kim_error_reference
  *
  *
  * \section types Types and Constants
diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h
index efa9a6dce..d18a5aae4 100644
--- a/src/include/kim/kim_ccache.h
+++ b/src/include/kim/kim_ccache.h
@@ -415,9 +415,9 @@ kim_error kim_ccache_copy (kim_ccache  *out_ccache,
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
  * \brief Compare ccache objects.
  */
-kim_error kim_ccache_compare (kim_ccache   in_ccache,
-                              kim_ccache   in_compare_to_ccache,
-                              kim_boolean *out_equal);
+kim_error kim_ccache_compare (kim_ccache      in_ccache,
+                              kim_ccache      in_compare_to_ccache,
+                              kim_comparison *out_comparison);
     
 /*!
  * \param in_ccache        a ccache object. 
@@ -531,7 +531,7 @@ kim_error kim_ccache_get_renewal_expiration_time (kim_ccache  in_ccache,
                                                   kim_time   *out_renewal_expiration_time);
 
 /*!
- * \param kim_ccache     a ccache object. 
+ * \param in_ccache      a ccache object. 
  * \param out_options    on exit, an options object reflecting the ticket
  *                       options of the credentials in \a in_ccache.
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h
index 222d1e760..e1303aeca 100644
--- a/src/include/kim/kim_credential.h
+++ b/src/include/kim/kim_credential.h
@@ -235,8 +235,14 @@ typedef int kim_credential_state;
  *     additional service credentials without resending shared secrets (such as a password)
  *     to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
  *
- * \li #kim_credential_is_valid() 
- *     returns whether the credential is valid and if not why the credential is not valid.
+ * \li #kim_credential_get_state() 
+ *     returns a #kim_credential_state containing the state of the credential.
+ *     Possible values are:
+ *     * kim_credentials_state_valid
+ *     * kim_credentials_state_expired
+ *     * kim_credentials_state_not_yet_valid
+ *     * kim_credentials_state_needs_validation
+ *     * kim_credentials_state_address_mismatch
  *
  * \li #kim_credential_get_start_time() 
  *     returns when the credential will become valid.  
diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h
index 8f10168f9..cd50a4080 100644
--- a/src/include/kim/kim_identity.h
+++ b/src/include/kim/kim_identity.h
@@ -106,9 +106,7 @@ extern "C" {
  * password when it has expired.
  *
  * #kim_identity_change_password() presents a user interface to obtain the old and 
- * new passwords from the user.  #kim_identity_change_password_with_passwords() takes 
- * the old and new passwords as input, but may still present a user interface if it 
- * needs to obtain additional information to authenticate.  
+ * new passwords from the user.   
  *
  * \note Not all identities have a password. Some sites use certificates (pkinit) 
  * and in the future there may be other authentication mechanisms (eg: smart cards).
diff --git a/src/include/kim/kim_library.h b/src/include/kim/kim_library.h
index bd0e73bb5..681f58e79 100644
--- a/src/include/kim/kim_library.h
+++ b/src/include/kim/kim_library.h
@@ -28,21 +28,56 @@
 
 #include <kim/kim.h>
 
+/*!
+ * \defgroup kim_library_reference KIM Library Documentation
+ * @{
+ */
+
+/*! Do not present user interface */
 #define KIM_UI_ENVIRONMENT_NONE 0
+/*! Automatically determine what user interface is appropriate (default). */
 #define KIM_UI_ENVIRONMENT_AUTO 1
+/*! Present a graphical user interface */
 #define KIM_UI_ENVIRONMENT_GUI  2
+/*! Present a command line user interface */
 #define KIM_UI_ENVIRONMENT_CLI  3
 
+/*! An integer describing the type of user interface to use. */
 typedef int kim_ui_environment;
 
-
+/*!
+ * \param in_ui_environment   an integer value describing the type of user interface to use.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \note Set to KIM_UI_ENVIRONMENT_AUTO by default.
+ * \brief Tell KIM how to present UI from your application.
+ */
 kim_error kim_library_set_ui_environment (kim_ui_environment in_ui_environment);
 
+/*!
+ * \param in_allow_access   a boolean containing whether or not to touch the user's home directory.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \note This API is usually used for Kerberos authenticated home directories to prevent a deadlock.
+ * \brief Tells KIM whether or not it is allowed to touch the user's home directory.
+ */
 kim_error kim_library_set_allow_home_directory_access (kim_boolean in_allow_access);
 
+/*!
+ * \param in_allow_automatic_prompting   a boolean containing whether or not to prompt automatically.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \brief Tells KIM whether or not it is allowed to automatically present user interface.
+ */
 kim_error kim_library_set_allow_automatic_prompting (kim_boolean in_allow_automatic_prompting);
 
+/*!
+ * \param in_application_name   a string containing the localized name of your application.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \note On many operating systems KIM can determine the caller's application
+ * name automatically.  This call exists for applications to use when those
+ * mechanisms fail or do not exist.
+ * \brief Set the name of your application for KIM to use for user interface.
+ */
 kim_error kim_library_set_application_name (kim_string in_application_name);
 
+/*!@}*/
 
 #endif /* KIM_LIBRARY_H */
diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h
index fd9797523..bce010cdd 100644
--- a/src/include/kim/kim_preferences.h
+++ b/src/include/kim/kim_preferences.h
@@ -350,7 +350,7 @@ kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences  in
                                                              kim_count       *out_number_of_identities);
 
 /*!
- * \param kim_preferences    a preferences object.
+ * \param in_preferences     a preferences object.
  * \param in_index           a index into the identities list (starting at 0).
  * \param out_identity       on exit, the identity at \a in_index in \a in_preferences.
  *                           Must be freed with kim_string_free().
diff --git a/src/include/kim/kim_selection_hints.h b/src/include/kim/kim_selection_hints.h
index afeae635e..1abbd0211 100644
--- a/src/include/kim/kim_selection_hints.h
+++ b/src/include/kim/kim_selection_hints.h
@@ -115,10 +115,10 @@ extern "C" {
  *
  * Once you have provided search criteria for selecting an identity, use
  * #kim_selection_hints_get_identity() to obtain an identity object.  
- * You can then use #kim_identity_get_gss_name() to obtain a gss_name_t 
- * for use in gss_acquire_cred() or use 
- * #kim_ccache_create_from_client_identity() to obtain a ccache containing 
- * credentials for the identity.
+ * You can then use #kim_identity_get_string() to obtain a krb5 principal
+ * string for use with gss_import_name() and gss_acquire_cred().  Alternatively, 
+ * you can use #kim_ccache_create_from_client_identity() to obtain a ccache  
+ * containing credentials for the identity.
  *
  * \note #kim_selection_hints_get_identity() obtains an identity based on
  * the current state of the selection hints object.  If you change the 
@@ -190,7 +190,7 @@ extern "C" {
  * mechanism for determining the name of the calling process.  If your 
  * application runs on one of these platforms (or is cross-platform) 
  * you should provide a localized version of its name with 
- * #kim_library_set_application_name().
+ * the private function #kim_library_set_application_name().
  *
  * In many cases a single application may select different identities for 
  * different purposes.  For example an email application might use different 
@@ -218,11 +218,28 @@ extern "C" {
  * @{
  */
 
+/*! A client identity in this realm. 
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_client_realm     "kim_hint_key_client_realm"
+
+/*! A client identity whose first component is this user string. 
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_user             "kim_hint_key_user"
+
+/*! A client identity which has obtained a service credential for this realm.
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_service_realm    "kim_hint_key_service_realm"
+
+/*! A client identity which has obtained a service credential for this service. 
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_service          "kim_hint_key_service"
+
+/*! A client identity which has obtained a service credential for this server.
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_server           "kim_hint_key_server"
+
+/*! The client identity which has obtained a service credential for this service identity. 
+ * See \ref kim_selection_hints_overview for more information */
 #define kim_hint_key_service_identity "kim_hint_key_service_identity"
     
 /*!
diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h
index dfd220ffe..f68f4a409 100644
--- a/src/include/kim/kim_string.h
+++ b/src/include/kim/kim_string.h
@@ -57,7 +57,7 @@ extern "C" {
  * To avoid this problem, KIM maintains an explanatory string for the last 
  * error seen in each thread calling into KIM.  If a caller wishes to display
  * an error to the user, immediately after getting the error the caller should
- * call #kim_string_create_for_error() to obtain a copy of the  
+ * call #kim_string_create_for_last_error() to obtain a copy of the  
  * descriptive error message.
  *
  * See \ref kim_string_reference for information on specific APIs.
diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h
index 8cf97246e..a871410bb 100644
--- a/src/include/kim/kim_types.h
+++ b/src/include/kim/kim_types.h
@@ -37,10 +37,13 @@ extern "C" {
  */
 
 /*!
- * The KIM Error type.  See \ref kim_error_overview for more information.
+ * The KIM Error type.
  */
 typedef int32_t     kim_error;
 
+/*!
+ * No error value for the kim_error type.  
+ */
 #define KIM_NO_ERROR ((kim_error) 0)
 
 /*!
@@ -68,44 +71,33 @@ typedef int         kim_boolean;
  * \li Less than 0 means the first object is less than the second.
  * \li 0 means the two objects are identical.
  * \li Greater than 0 means the first object is greater than the second.
- * \note Convenience macros are provided for interpreting kim_comparison_ts
- * to improve code readability.
- * See #kim_comparison_is_less_than(), #kim_comparison_is_equal() and 
+ * \note Convenience macros are provided for interpreting #kim_comparison
+ * values to improve code readability.
+ * See #kim_comparison_is_less_than(), #kim_comparison_is_equal_to() and 
  * #kim_comparison_is_greater_than()
  */
 typedef int         kim_comparison;
 
 /*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
  */
 #define kim_comparison_is_less_than(c)    (c < 0)
 
 /*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
  */
 #define kim_comparison_is_equal_to(c)        (c == 0) 
 
 /*!
- * Convenience macro for interpreting #kim_comparison_t.
+ * Convenience macro for interpreting #kim_comparison.
  */
 #define kim_comparison_is_greater_than(c) (c > 0)
 
 /*!
- * The KIM Context type.  See \ref kim_context_overview for more information.
- */
-typedef const char *kim_context;
-
-/*!
  * The KIM String type.  See \ref kim_string_overview for more information.
  */
 typedef const char *kim_string;
 
-//struct kim_error_opaque;
-/*!
- * A KIM Error object.  See \ref kim_error_overview for more information.
- */
-//typedef struct kim_error_opaque *kim_error;
-
 struct kim_identity_opaque;
 /*!
  * A KIM Principal object.  See \ref kim_identity_overview for more information.
@@ -144,7 +136,7 @@ typedef struct kim_ccache_opaque *kim_ccache;
 
 struct kim_credential_iterator_opaque;
 /*!
- * A KIM Credential Iterator object.  See \ref kim_credential_iterator_t for more information.
+ * A KIM Credential Iterator object.  See \ref kim_credential_iterator for more information.
  */
 typedef struct kim_credential_iterator_opaque *kim_credential_iterator;