-/*
- * Wait for a session clear operation to complete.
- *
- * A negative timeout_ms value can be used to wait indefinitely.
- *
- * Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
- * operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
- * to indicate that the wait timed out.
- * On error, one of the negative lttng_clear_handle_status is returned.
- *
- * Note: This function returning a success status does not mean that
- * the clear operation itself succeeded; it indicates that the _wait_
- * operation completed successfully.
- */
+/*!
+@brief
+ Waits for the \lt_obj_session clearing operation identified by
+ \lt_p{handle} to complete.
+
+If this function returns #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED, then the
+recording session clearing operation identified by \lt_p{handle}
+completed. This doesn't mean, however, that the clearing operation
+itself succeeded; use lttng_clear_handle_get_result() to know this.
+
+@param[in] handle
+ Recording session clearing handle which identifies the clearing
+ operation of which to wait for completion.
+@param[in] timeout_ms
+ Maximum time (milliseconds) to wait for the completion of the
+ recording session clearing operation identified by \lt_p{handle}
+ before returning #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT, or
+ <code>-1</code> to wait indefinitely.
+
+@retval #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED
+ The recording session clearing operation identified by \lt_p{handle}
+ completed (with or without success).
+@retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT
+ The function waited for the completion of the recording session
+ clearing operation for more than \lt_p{timeout_ms} ms.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+
+@sa lttng_clear_handle_get_result() --
+ Returns whether or not a recording session clearing operation
+ succeeded.
+*/