--- a/ucx/cx/collection.h	Sat Oct 04 14:54:25 2025 +0200
+++ b/ucx/cx/collection.h	Sun Oct 19 21:20:08 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