DEVICE: Document return status for device APIs (#10940)

Author: michal-shalev

src/ucp/api/device/ucp_device_impl.h

@@ -133,6 +133,10 @@ UCS_F_DEVICE ucs_status_t ucp_device_prepare_send(
  * @param [in]  flags           Flags usable to modify the function behavior.
  * @param [out] req             Request populated by the call.
  *
+ * @return UCS_INPROGRESS     - Operation successfully posted. If @a req is not
+ *                              NULL, use @ref ucp_device_progress_req to check
+ *                              for completion.
+ * @return UCS_OK             - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level = UCS_DEVICE_LEVEL_THREAD>
@@ -188,6 +192,10 @@ UCS_F_DEVICE ucs_status_t ucp_device_put_single(
  * @param [in]  flags           Flags usable to modify the function behavior.
  * @param [out] req             Request populated by the call.
  *
+ * @return UCS_INPROGRESS     - Operation successfully posted. If @a req is not
+ *                              NULL, use @ref ucp_device_progress_req to check
+ *                              for completion.
+ * @return UCS_OK             - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level = UCS_DEVICE_LEVEL_THREAD>
@@ -243,6 +251,11 @@ UCS_F_DEVICE ucs_status_t ucp_device_counter_inc(
  * @param [in]  flags                  Flags to modify the function behavior.
  * @param [out] req                    Request populated by the call.
  *
+ * @return UCS_INPROGRESS            - Operation successfully posted. If @a req
+ *                                     is not NULL, use @ref
+ *                                     ucp_device_progress_req to check for
+ *                                     completion.
+ * @return UCS_OK                    - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level = UCS_DEVICE_LEVEL_THREAD>
@@ -321,6 +334,11 @@ UCS_F_DEVICE ucs_status_t ucp_device_put_multi(
  * @param [in]  flags                  Flags to modify the function behavior.
  * @param [out] req                    Request populated by the call.
  *
+ * @return UCS_INPROGRESS            - Operation successfully posted. If @a req
+ *                                     is not NULL, use @ref
+ *                                     ucp_device_progress_req to check for
+ *                                     completion.
+ * @return UCS_OK                    - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level = UCS_DEVICE_LEVEL_THREAD>
@@ -410,7 +428,7 @@ UCS_F_DEVICE void ucp_device_counter_write(void *counter_ptr, uint64_t value)
  *
  * @tparam      level  Level of cooperation of the transfer.
  * @param [in]  req    Request containing operations in progress and channel to progress.
- * 
+ *
  * @return UCS_OK           - The request has completed, no more operations are
  *                            in progress.
  * @return UCS_INPROGRESS   - One or more operations in the request batch

src/uct/api/device/uct_device_impl.h

@@ -42,6 +42,11 @@ union uct_device_completion {
  * @param [in]  flags           Flags to modify the function behavior.
  * @param [in]  comp            Completion object to track the progress of operation.
  *
+ * @return UCS_INPROGRESS     - Operation successfully posted, use @ref
+ *                              uct_device_ep_progress and @ref
+ *                              uct_device_ep_check_completion to
+ *                              check for completion.
+ * @return UCS_OK             - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level>
@@ -83,6 +88,11 @@ UCS_F_DEVICE ucs_status_t uct_device_ep_put_single(
  * @param [in]  flags           Flags to modify the function behavior.
  * @param [in]  comp            Completion object to track the progress of operation.
  *
+ * @return UCS_INPROGRESS      - Operation successfully posted, use @ref
+ *                               uct_device_ep_progress and @ref
+ *                               uct_device_ep_check_completion to check
+ *                               for completion.
+ * @return UCS_OK              - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level>
@@ -139,6 +149,11 @@ UCS_F_DEVICE ucs_status_t uct_device_ep_atomic_add(
  * @param [in]  flags                  Flags to modify the function behavior.
  * @param [out] req                    Request populated by the call.
  *
+ * @return UCS_INPROGRESS            - Operation successfully posted, use @ref
+ *                                     uct_device_ep_progress and @ref
+ *                                     uct_device_ep_check_completion to check
+ *                                     for completion.
+ * @return UCS_OK                    - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level>
@@ -215,6 +230,11 @@ UCS_F_DEVICE ucs_status_t uct_device_ep_put_multi(
  * @param [in]  flags                  Flags to modify the function behavior.
  * @param [in]  comp                   Completion object to track progress.
  *
+ * @return UCS_INPROGRESS            - Operation successfully posted, use @ref
+ *                                     uct_device_ep_progress and @ref
+ *                                     uct_device_ep_check_completion to check
+ *                                     for completion.
+ * @return UCS_OK                    - Operation completed successfully.
  * @return Error code as defined by @ref ucs_status_t
  */
 template<ucs_device_level_t level>