Clarify krb5_kt_resolve() API documentation

Explicitly say to use krb5_kt_close() like we do for most other
allocating API calls.  Note the default type.  Instead of saying "The
key table is not opened," say that the keytab file for FILE keytabs is
not opened by this call.

ticket: 8508 (new)
target_version: 1.14-next
target_version: 1.15-next
tags: pullup

1 files changed, 6 insertions, 5 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 64b0d0f..4ed4d35 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -4213,13 +4213,14 @@ krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
  * @param [out] ktid            Key table handle
  *
  * Resolve the key table name @a name and set @a ktid to a handle identifying
- * the key table.  The key table is not opened.
+ * the key table.  Use krb5_kt_close() to free @a ktid when it is no longer
+ * needed.
  *
- * @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.
+ * @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.  If no @a type is given, the default is @c FILE.
  *
- * @sa krb5_kt_close()
+ * If @a name is of type @c FILE, the keytab file is not opened by this call.
  *
  * @code
  *  Example: krb5_kt_resolve(context, "FILE:/tmp/filename", &ktid);