diff -r 3106d9ca2f9c -r f3ab28ed22e5 ucx/cx/collection.h
--- a/ucx/cx/collection.h	Mon Oct 13 21:07:59 2025 +0200
+++ b/ucx/cx/collection.h	Mon Oct 13 21:31:58 2025 +0200
@@ -142,8 +142,10 @@
 /**
  * Indicates whether the collection can guarantee that the stored elements are currently sorted.
  *
- * This may return false even when the elements are sorted.
- * It is totally up to the implementation of the collection whether it keeps track of the order of its elements.
+ * This may return @c false even when the elements are sorted.
+ * It is totally up to the implementation of the collection when to check if the elements are sorted.
+ * It is usually a good practice to establish this property as an invariant that does not need
+ * to be re-checked on certain operations.
  *
  * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
  * @retval true if the elements are currently sorted wrt. the collection's compare function