From e9d20a1590a0cc059d4e3475ccdbcbc22dc6e1ac Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Sat, 26 Apr 2025 07:05:01 +0900
Subject: [PATCH] doc/limitations.md: document double dispatch removal

We have removed `append_features`/`prepend_features`/`extend_object`.
It is incompatible with CRuby, but simpler.
---
 doc/limitations.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/limitations.md b/doc/limitations.md
index 1b3eccbc9..bbe33707e 100644
--- a/doc/limitations.md
+++ b/doc/limitations.md
@@ -186,3 +186,30 @@ def g(a: 1, b: a)
 end
 g(a:1)
 ```
+
+## No Double Dispatch in Module Loading
+
+To make implementation simpler, mruby does not use double dispatching in module loading (`include`/`prepend`/`extend`).
+Those method internally called corresponding actual load methods (`append_features`/`prepend_features`/`extend_object`).
+But they are rarely overloaded, consumes more memory, and make loading little bit slower. As a Ruby implementation for the smaller device,
+we decided mruby simpler.
+
+```ruby
+module M
+  def self.append_features(mod)
+     p :append
+  end
+end
+
+class C
+  include M
+end
+```
+
+#### Ruby [ruby 3.5.0dev (2025-04-21 85bab61565))]
+
+Prints `:append`.
+
+#### mruby [3.5.0 (2025-04-28)]
+
+Nothing printed (since `include` does not call `append_features` internally).