Update doxygen markup in krb5.hin

A few places were using the standard C /* comment */ form, but
this is rendered poorly by doxygen through to our Sphinx bridge.
Use the special /**< comment */ form to get doxygen-specific behavior.
If the standard C comment form is used, the full comment (including
start and end markers) is included in the value of the macro, and
Sphinx then tries to treat the end of the comment as the start of
inline markup with no corresponding end-string, which is a warning.
Using the doxygen form of the comment, the contents of the comment
are put in a separate paragraph block, which is inserted in the
body of the generated RST document.

The markup for krb5_rd_priv() had a line that ended with an @c
markup statement without a symbol following it.  This confused
doxygen into not parsing any more of the comment.  The beginning
of the next line is a macro identifier with markup to auto-linkify it.
In RST, it is not possible to have a link and a terminal font on the
same text, so removing the @c is the appropriate fix.

There are also eleven deprecated functions which are replaced by
the krb5_c_* family of functions.  However, referring to this class
of functions as the "krb5_c_" class of functions results in Sphinx
attempting to interpret this statement as a link to a label elsewhere
in the document, and no such label exists.  To avoid this warning, use
"krb5_c_*" to refer to the class of functions, which is arguably
more correct anyways.

ticket: 7447
tags: pullup
target_version: 1.11

1 files changed, 20 insertions, 20 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index a9e887e19b..b83c91c1ea 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -771,7 +771,7 @@ krb5_c_random_make_octets(krb5_context context, krb5_data *data);
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_c_random_seed(krb5_context context, krb5_data *data);
 
@@ -965,11 +965,11 @@ krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
  * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL:
  * it is used for hardware Pre-athentication @a and KDC referrals.
  */
-#define KRB5_KEYUSAGE_PA_REFERRAL               26 /* XXX note conflict with above */
+#define KRB5_KEYUSAGE_PA_REFERRAL               26 /**< XXX note conflict */
 
 /* Defined in [MS-SFU] */
-#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST  26 /* XXX note conflict with above */
-#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY    27 /* XXX note conflict with above */
+#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST  26 /**< XXX note conflict */
+#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY    27 /**< XXX note conflict */
 
 #define KRB5_KEYUSAGE_AD_SIGNEDPATH             -21
 #define KRB5_KEYUSAGE_IAKERB_FINISHED           42
@@ -1511,24 +1511,24 @@ krb5_k_prf(krb5_context context, krb5_key key, krb5_data *input, krb5_data *outp
  * old cryptosystem routine prototypes.  These are now layered
  * on top of the functions above.
  */
-/** @deprecated Replaced by krb5_c_ API family.*/
+/** @deprecated Replaced by krb5_c_* API family.*/
 krb5_error_code KRB5_CALLCONV
 krb5_encrypt(krb5_context context, krb5_const_pointer inptr,
              krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
              krb5_pointer ivec);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_decrypt(krb5_context context, krb5_const_pointer inptr,
              krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
              krb5_pointer ivec);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_process_key(krb5_context context, krb5_encrypt_block *eblock,
                  const krb5_keyblock * key);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_finish_key(krb5_context context, krb5_encrypt_block * eblock);
 
@@ -1538,31 +1538,31 @@ krb5_string_to_key(krb5_context context, const krb5_encrypt_block *eblock,
                    krb5_keyblock * keyblock, const krb5_data *data,
                    const krb5_data *salt);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_init_random_key(krb5_context context, const krb5_encrypt_block *eblock,
                      const krb5_keyblock *keyblock, krb5_pointer *ptr);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_finish_random_key(krb5_context context, const krb5_encrypt_block *eblock,
                        krb5_pointer *ptr);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_random_key(krb5_context context, const krb5_encrypt_block *eblock,
                 krb5_pointer ptr, krb5_keyblock **keyblock);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_enctype KRB5_CALLCONV
 krb5_eblock_enctype(krb5_context context, const krb5_encrypt_block *eblock);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 krb5_error_code KRB5_CALLCONV
 krb5_use_enctype(krb5_context context, krb5_encrypt_block *eblock,
                  krb5_enctype enctype);
 
-/** @deprecated Replaced by krb5_c_ API family. */
+/** @deprecated Replaced by krb5_c_* API family. */
 size_t KRB5_CALLCONV
 krb5_encrypt_size(size_t length, krb5_enctype crypto);
 
@@ -1825,7 +1825,7 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
 
 #define KRB5_SAM_USE_SAD_AS_KEY         0x80000000
 #define KRB5_SAM_SEND_ENCRYPTED_SAD     0x40000000
-#define KRB5_SAM_MUST_PK_ENCRYPT_SAD    0x20000000 /* currently must be zero */
+#define KRB5_SAM_MUST_PK_ENCRYPT_SAD    0x20000000 /**< currently must be zero */
 
 /** Transited encoding types */
 #define KRB5_DOMAIN_X500_COMPRESS               1
@@ -1846,7 +1846,7 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
 #define KRB5_AUTHDATA_OSF_DCE   64
 #define KRB5_AUTHDATA_SESAME    65
 #define KRB5_AUTHDATA_WIN2K_PAC 128
-#define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129     /* RFC 4537 */
+#define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129     /**< RFC 4537 */
 #define KRB5_AUTHDATA_SIGNTICKET        512     /**< formerly 142 in krb5 1.8 */
 #define KRB5_AUTHDATA_FX_ARMOR 71
 /** @} */ /* end of KRB5_AUTHDATA group */
@@ -1859,9 +1859,9 @@ krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
 #define KRB5_KPASSWD_SOFTERROR          4  /**< Password change rejected */
 /* These are Microsoft's extensions in RFC 3244, and it looks like
    they'll become standardized, possibly with other additions.  */
-#define KRB5_KPASSWD_ACCESSDENIED       5       /* unused */
+#define KRB5_KPASSWD_ACCESSDENIED       5       /**< unused */
 #define KRB5_KPASSWD_BAD_VERSION        6
-#define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7      /* unused */
+#define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7      /**< unused */
 
 /*
  * end "proto.h"
@@ -2738,7 +2738,7 @@ typedef struct krb5_rc_st *krb5_rcache;
 
 
 /* XXX */
-#define MAX_KEYTAB_NAME_LEN 1100 /* Long enough for MAXPATHLEN + some extra */
+#define MAX_KEYTAB_NAME_LEN 1100 /**< Long enough for MAXPATHLEN + some extra */
 
 typedef krb5_pointer krb5_kt_cursor;
 
@@ -3378,7 +3378,7 @@ krb5_rd_safe(krb5_context context, krb5_auth_context auth_context,
  * This function parses a @c KRB-PRIV message, verifies its integrity, and
  * stores its unencrypted data into @a outbuf.
  *
- * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or @c
+ * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or
  *       #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, @a
  *       outdata is required.
  *