Document some GSS-API functions and fix some spelling errors. No code changes.

Signed-off-by: Love Hornquist Astrand <lha@h5l.org>

lib/gssapi/mech/doxygen.c

@@ -39,13 +39,12 @@
  * - SPNEGO
  * - NTLM
  *
- * See @ref gssapi_mechs for more describtion about these mechanisms.
- *
- * The project web page: http://www.h5l.org/
+ * @sa
  *
  * - @ref gssapi_services_intro
  * - @ref gssapi_mechs
  * - @ref gssapi_api_INvsMN
+ * - The project web page: http://www.h5l.org/
  */
 
 /**
@@ -105,27 +104,27 @@
  * @page internalVSmechname Internal names and mechanism names
  * @section gssapi_api_INvsMN Name forms
  *
- * There are two forms of name in GSS-API, Internal form and
- * Contiguous string ("flat") form. gss_export_name() and
+ * There are two name representations in GSS-API: Internal form and
+ * Contiguous string ("flat") form. Functions gss_export_name() and
  * gss_import_name() can be used to convert between the two forms.
  *
  * - The contiguous string form is described by an oid specificing the
  *   type and an octet string. A special form of the contiguous
  *   string form is the exported name object. The exported name
  *   defined for each mechanism, is something that can be stored and
- *   complared later. The exported name is what should be used for
+ *   compared later. The exported name is what should be used for
  *   ACLs comparisons.
  *
- * - The Internal form
+ * - The Internal form is opaque to the application programmer and
+ *   is implementation-dependent.
  *
- *   There is also special form of the Internal Name (IN), and that is
+ * - There is also a special form of the Internal Name (IN), and that is
  *   the Mechanism Name (MN). In the mechanism name all the generic
  *   information is stripped of and only contain the information for
  *   one mechanism.  In GSS-API some function return MN and some
  *   require MN as input. Each of these function is marked up as such.
  *
- *
- * Describe relationship between import_name, canonicalize_name,
+ * @TODO Describe relationship between import_name, canonicalize_name,
  * export_name and friends.
  */
 

lib/gssapi/mech/gss_display_status.c

@@ -134,25 +134,43 @@ supplementary_error(OM_uint32 v)
 	return msgs[v];
 }
 
-
+/**
+ * Convert a GSS-API status code to text
+ *
+ * @param minor_status     minor status code
+ * @param status_value     status value to convert
+ * @param status_type      One of:
+ *                         GSS_C_GSS_CODE - status_value is a GSS status code,
+ *                         GSS_C_MECH_CODE - status_value is a mechanism status code
+ * @param mech_type        underlying mechanism. Use GSS_C_NO_OID to obtain the
+ *                         system default.
+ * @param message_context  state information to extract further messages from the
+ *                         status_value
+ * @param status_string    the allocated text representation. Release with
+ *                         gss_release_buffer()
+ *
+ * @returns a gss_error code.
+ *
+ * @ingroup gssapi
+ */
 GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL
 gss_display_status(OM_uint32 *minor_status,
     OM_uint32 status_value,
     int status_type,
     const gss_OID mech_type,
-    OM_uint32 *message_content,
+    OM_uint32 *message_context,
     gss_buffer_t status_string)
 {
 	OM_uint32 major_status;
 
 	_mg_buffer_zero(status_string);
-	*message_content = 0;
+	*message_context = 0;
 
 	major_status = _gss_mg_get_error(mech_type, status_type,
 					 status_value, status_string);
 	if (major_status == GSS_S_COMPLETE) {
 
-	    *message_content = 0;
+	    *message_context = 0;
 	    *minor_status = 0;
 	    return GSS_S_COMPLETE;
 	}

lib/gssapi/mech/gss_export_name.c

@@ -28,6 +28,20 @@
 
 #include "mech_locl.h"
 
+/**
+ * Convert a GGS-API name from internal form to contiguous string.
+ *
+ * @sa gss_import_name(), @ref internalVSmechname.
+ *
+ * @param minor_status   minor status code
+ * @param input_name     input name in internal name form
+ * @param exported_name  output name in contiguos string form
+ *
+ * @returns a gss_error code, see gss_display_status() about printing
+ *        the error code.
+ *
+ * @ingroup gssapi
+ */
 GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL
 gss_export_name(OM_uint32 *minor_status,
     const gss_name_t input_name,

lib/gssapi/mech/gss_import_name.c

@@ -149,7 +149,7 @@ _gss_import_export_name(OM_uint32 *minor_status,
 }
 
 /**
- * Import a name internal or mechanism name
+ * Convert a GGS-API name from contiguous string to internal form.
  *
  * Type of name and their format:
  * - GSS_C_NO_OID
@@ -159,12 +159,12 @@ _gss_import_export_name(OM_uint32 *minor_status,
  * - GSS_C_NT_ANONYMOUS
  * - GSS_KRB5_NT_PRINCIPAL_NAME
  *
- * For more information about @ref internalVSmechname.
+ * @sa gss_export_name(), @ref internalVSmechname.
  *
- * @param minor_status minor status code
- * @param input_name_buffer import name buffer
- * @param input_name_type type of the import name buffer
- * @param output_name the resulting type, release with
+ * @param minor_status       minor status code
+ * @param input_name_buffer  import name buffer
+ * @param input_name_type    type of the import name buffer
+ * @param output_name        the resulting type, release with
  *        gss_release_name(), independent of input_name
  *
  * @returns a gss_error code, see gss_display_status() about printing

lib/krb5/sendauth.c

@@ -60,6 +60,29 @@
  * }
  */
 
+/**
+ * Perform the client side of the sendauth protocol.
+ *
+ * @param context        Kerberos 5 context.
+ * @param auth_context   Authentication context of the peer.
+ * @param p_fd           Socket associated to the connection.
+ * @param appl_version   Server-specific string.
+ * @param client         Client principal. If NULL, use the credentials in \a ccache.
+ * @param server         Server principal.
+ * @param ap_req_options Options for the AP_REQ message. See the AP_OPTS_* defines in krb5.h.
+ * @param in_data        FIXME
+ * @param in_creds       FIXME
+ * @param ccache         Credentials cache. If NULL, use the default credentials cache.
+ * @param ret_error      If not NULL, will be set to the error reported by server, if any.
+ *                       Must be deallocated with krb5_free_error_contents().
+ * @param rep_result     If not NULL, will be set to the EncApRepPart of the AP_REP message.
+ *                       Must be deallocated with krb5_free_ap_rep_enc_part().
+ * @param out_creds      FIXME If not NULL, will be set to FIXME. Must be deallocated with
+ *                       krb5_free_creds().
+ *
+ * @return 0 to indicate success. Otherwise a Kerberos error code is
+ *         returned, see krb5_get_error_message().
+ */
 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
 krb5_sendauth(krb5_context context,
 	      krb5_auth_context *auth_context,