Amend KDC hook documentation

In the Doxygen comments for the new APIs and types, include @version
tags indicating that they are new in 1.15, and put @param declarations
just after the brief message for consistency with other comments.

ticket: 8386

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index c045ee3770a09595965c28cd160ad0288b96c3a0..f52a9ea90ce48f89401fcff66273f6bf7eef5e41 100644 (file)
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -8302,6 +8302,13 @@ krb5_set_trace_filename(krb5_context context, const char *filename);
 /**
  * Hook function for inspecting or modifying messages sent to KDCs.
  *
+ * @param [in]  context         Library context
+ * @param [in]  data            Callback data
+ * @param [in]  realm           The realm the message will be sent to
+ * @param [in]  message         The original message to be sent to the KDC
+ * @param [out] new_message_out Optional replacement message to be sent
+ * @param [out] reply_out       Optional synthetic reply
+ *
  * If the hook function returns an error code, the KDC communication will be
  * aborted and the error code will be returned to the library operation which
  * initiated the communication.
@@ -8319,12 +8326,7 @@ krb5_set_trace_filename(krb5_context context, const char *filename);
  * @a new_message_out or @a reply_out, to ensure that it can be freed correctly
  * by the library.
  *
- * @param [in]  context         Library context
- * @param [in]  data            Callback data
- * @param [in]  realm           The realm the message will be sent to
- * @param [in]  message         The original message to be sent to the KDC
- * @param [out] new_message_out Optional replacement message to be sent
- * @param [out] reply_out       Optional synthetic reply
+ * @version New in 1.15
  *
  * @retval 0 Success
  * @return A Kerberos error code
@@ -8339,6 +8341,14 @@ typedef krb5_error_code
 /**
  * Hook function for inspecting or overriding KDC replies.
  *
+ * @param [in]  context         Library context
+ * @param [in]  data            Callback data
+ * @param [in]  code            Status of KDC communication
+ * @param [in]  realm           The realm the reply was received from
+ * @param [in]  message         The message sent to the realm's KDC
+ * @param [in]  reply           The reply received from the KDC
+ * @param [out] new_reply_out   Optional replacement reply
+ *
  * If @a code is zero, @a reply contains the reply received from the KDC.  The
  * hook function may return an error code to simulate an error, may synthesize
  * a different reply by setting @a new_reply_out, or may simply return
@@ -8351,13 +8361,7 @@ typedef krb5_error_code
  * The hook function should use krb5_copy_data() to construct the value for
  * @a new_reply_out, to ensure that it can be freed correctly by the library.
  *
- * @param [in]  context         Library context
- * @param [in]  data            Callback data
- * @param [in]  code            Status of KDC communication
- * @param [in]  realm           The realm the reply was received from
- * @param [in]  message         The message sent to the realm's KDC
- * @param [in]  reply           The reply received from the KDC
- * @param [out] new_reply_out   Optional replacement reply
+ * @version New in 1.15
  *
  * @retval 0 Success
  * @return A Kerberos error code
@@ -8373,13 +8377,15 @@ typedef krb5_error_code
 /**
  * Set a KDC pre-send hook function.
  *
+ * @param [in] context          Library context
+ * @param [in] send_hook        Hook function (or NULL to disable the hook)
+ * @param [in] data             Callback data to be passed to @a send_hook
+ *
  * @a send_hook will be called before messages are sent to KDCs by library
  * functions such as krb5_get_credentials().  The hook function may inspect,
  * override, or synthesize its own reply to the message.
  *
- * @param [in] context          Library context
- * @param [in] send_hook        Hook function (or NULL to disable the hook)
- * @param [in] data             Callback data to be passed to @a send_hook
+ * @version New in 1.15
  */
 void KRB5_CALLCONV
 krb5_set_kdc_send_hook(krb5_context context, krb5_pre_send_fn send_hook,
@@ -8388,14 +8394,16 @@ krb5_set_kdc_send_hook(krb5_context context, krb5_pre_send_fn send_hook,
 /**
  * Set a KDC post-receive hook function.
  *
+ * @param [in] context          The library context.
+ * @param [in] recv_hook        Hook function (or NULL to disable the hook)
+ * @param [in] data             Callback data to be passed to @a recv_hook
+ *
  * @a recv_hook will be called after a reply is received from a KDC during a
  * call to a library function such as krb5_get_credentials().  The hook
  * function may inspect or override the reply.  This hook will not be executed
  * if the pre-send hook returns a synthetic reply.
  *
- * @param [in] context          The library context.
- * @param [in] recv_hook        Hook function (or NULL to disable the hook)
- * @param [in] data             Callback data to be passed to @a recv_hook
+ * @version New in 1.15
  */
 void KRB5_CALLCONV
 krb5_set_kdc_recv_hook(krb5_context context, krb5_post_recv_fn recv_hook,