1 files changed, 6 insertions, 0 deletions
diff --git a/enum.c b/enum.c
index 62bcfba395..b328003425 100644
--- a/enum.c
+++ b/enum.c
@@ -934,6 +934,9 @@ enum_first(int argc, VALUE *argv, VALUE obj)
  *  built-in Schwartzian Transform, useful when key computation or
  *  comparison is expensive.
  *
+ *  The result is not guaranteed as stable.  When comparison of two
+ *  elements returns +0+, the order of the elements is unpredictable.
+ *
  *     %w(rhea kea flea).sort          #=> ["flea", "kea", "rhea"]
  *     (1..10).sort { |a, b| b <=> a }  #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
  */
@@ -1004,6 +1007,9 @@ sort_by_cmp(const void *ap, const void *bp, void *data)
  *  Sorts <i>enum</i> using a set of keys generated by mapping the
  *  values in <i>enum</i> through the given block.
  *
+ *  The result is not guaranteed as stable.  When two keys are equal,
+ *  the order of the corresponding elements is unpredictable.
+ *
  *  If no block is given, an enumerator is returned instead.
  *
  *     %w{apple pear fig}.sort_by { |word| word.length}