UCT/API: Address review comments

openucx · Aug 25, 2023 · c498968 · c498968
1 parent 5c16073
commit c498968
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 15 deletions.
diff --git a/src/uct/api/uct.h b/src/uct/api/uct.h
@@ -827,13 +827,12 @@ enum uct_md_mem_flags {
     UCT_MD_MEM_ACCESS_LOCAL_WRITE   = UCS_BIT(9),
 
     /**
-      * Register the memory region so its remote access key would likely be
-      * equal to remote access keys received from other peers, when compared
-      * with @a uct_rkey_compare. This flag is a best-effort hint. When remote
-      * access keys received from different peers are compared equal, they can
-      * be used interchangeably, avoiding the need to keep all of them in
-      * memory.
-      */
+     * Register the memory region so its remote access key would likely be
+     * equal to remote access keys received from other peers, when compared
+     * with @a uct_rkey_compare. This flag is a hint. When remote access keys
+     * received from different peers are compared equal, they can be used
+     * interchangeably, avoiding the need to keep all of them in memory.
+     */
     UCT_MD_MEM_SYMMETRIC_RKEY       = UCS_BIT(10),
 
     /**

diff --git a/src/uct/api/v2/uct_v2.h b/src/uct/api/v2/uct_v2.h
@@ -980,22 +980,19 @@ ucs_status_t uct_ep_connect_to_ep_v2(uct_ep_h ep,
 /**
  * @ingroup UCT_MD
  *
- * @brief Compare two remote keys
+ * @brief This routine compares two remote keys.
  *
- * The comparison result is < 0 if rkey1 is lower than rkey2, 0 if they
- * are equal or > 0 if rkey1 is greater than rkey2. The remote key greater-than
- * semantic is arbitrary and implementation dependent, nevertheless it's
- * guaranteed to be consistent (transitive and antisymmetric). It can be used,
- * for example, to perform an efficient binary search in a sorted array of
- * remote keys.
+ * It sets the @a result argument to < 0 if rkey1 is lower than rkey2, 0 if they
+ * are equal or > 0 if rkey1 is greater than rkey2. It can be used for sorting.
  *
  * @param[in]  component  Component to use for the comparison
  * @param[in]  rkey1      First rkey to compare
  * @param[in]  rkey2      Second rkey to compare
  * @param[in]  params     Additional parameters for comparison
  * @param[out] result     Result of the comparison
  *
- * @return Error code or UCS_OK if result contains the comparison result
+ * @return UCS_OK         @a result contains the comparison result
+ *         Other          Error codes as defined by @ref ucs_status_t.
  */
 ucs_status_t
 uct_rkey_compare(uct_component_h component, uct_rkey_t rkey1, uct_rkey_t rkey2,