-/*
- * Get the status of the session rotation performed as part of the session's
- * destruction.
- *
- * A session will perform a final rotation if it was ever rotated over its
- * lifetime. If this happens, this function returns the state of the rotation
- * that was performed.
- *
- * This function must be used on a session destruction handle which was
- * successfully waited on.
- *
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session
- * rotation could be obtained. Check the value of 'rotation_state' to
- * determine if the rotation of the session completed successfully or not.
- *
- * On error, one of the negative lttng_destruction_handle_status is returned.
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
- * was not waited-on using the handle or if the arguments of the function are
- * invalid (e.g. NULL).
- *
- * Note that if no rotation was performed, rotation_state will be set to
- * LTTNG_ROTATION_STATE_NO_ROTATION.
- */
+/*!
+@brief
+ Sets \lt_p{*rotation_state} to the state of a final
+ \ref api_session_rotation "rotation" operation which the
+ destruction of the recording session identified by \lt_p{handle}
+ caused.
+
+You must successfully wait for the completion of the recording session
+destruction operation identified by \lt_p{handle} with
+lttng_destruction_handle_wait_for_completion() before you call this
+function.
+
+This function is only useful if LTTng performed at least one recording
+session rotation during the lifetime of the destroyed recording session.
+
+@param[in] handle
+ Handle of the destruction operation of the recording session of
+ which to get the state of the final rotation operation.
+@param[out] rotation_state
+ @parblock
+ <strong>On success</strong>, this function sets
+ \lt_p{*rotation_state} to the state of the final rotation operation
+ which the recording session destruction operation identified by
+ \lt_p{handle} caused.
+
+ \lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
+ didn't perform any final recording session rotation.
+ @endparblock
+
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
+ Success: \lt_p{*rotation_state} is the state of the final rotation
+ of the destroyed recording session.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ You successfully waited for the completion of the recording session
+ destruction operation identified by \lt_p{handle} with
+ lttng_destruction_handle_wait_for_completion().
+@lt_pre_not_null{rotation_state}
+
+@sa lttng_destruction_handle_get_archive_location() --
+ Get the location of the trace chunk archive which a recording
+ session destruction operation created.
+*/