1 files changed, 10 insertions, 0 deletions
diff --git a/gc.c b/gc.c
index d33a6fde51..262dfe7d04 100644
--- a/gc.c
+++ b/gc.c
@@ -2339,6 +2339,16 @@ id2ref(VALUE obj, VALUE objid)
  *
  *  The same number will be returned on all calls to +object_id+ for a given object,
  *  and no two active objects will share an id.
+ *
+ *  Note that some objects of builtin classes are reused for optimization.
+ *  This is the case for immediate values and frozen string litterals.
+ *  Immediate values are not passed by reference by are passed by value:
+ *  +nil+, +true+, +false+, Fixnums. Some Floats may be immediates too.
+ *
+ *      Object.new.object_id  == Object.new.object_id  # => false
+ *      (21 * 2).object_id    == (21 * 2).object_id    # => true
+ *      "hello".object_id     == "hello".object_id     # => false
+ *      "hi".freeze.object_id == "hi".freeze.object_id # => true
  */
 
 /*