RCR 346: Clarification of Module#included_modules

The current rdoc of Module#included_modules simply states that it "Returns the list of modules included in mod."

The actual implementation returns the list in the order in which the modules are searched for methods at runtime. Making this order explicit would be useful.

Recently on ruby-talk someone asked how to determine which module defined a method for a given class. I provided a code snippet which did this by using included_modules to simulate the search order for a method. This code works but relies on the undocumented feature of included_modules returning the list in the proper order.

The 1.8 implementation of included_modules basically walks the chain of 'classes' between the superclass of the module/class in question, and the 'superclass' of it's class, looking for 'classes' marked with a type of T_ICLASS. The word 'class' is in quotes here because in some cases, these are not visible Ruby classes but rather virtual or proxy classes.

The net effect of this implementation is that the list of included modules is the same as the run-time search order for methods.

It would be useful for such metaprogramming code if this feature was documented so that it would not be changed in future versions of Ruby without consideration.

The proposal is simply to change the documentation, and should have no impact on syntax or the semantics of existing implementations.

The documentation in question is the rdoc comment in class.c just before the C function rb_mod_included_modules, I would propose that this be changed to something like:

/*

 *  call-seq:
 *     mod.included_modules -> array
 *
 *  Returns the list of modules included in <i>mod</i>.
 *  The elements of this list are in the order in which 
 *  modules are examined in finding a method for mod,
 *  that is, they are in the reverse chronological order
 *  in which the modules were included.
 *
 *     module Mixin
 *     end
 *
 *     module Mixin2
 *     end
 *
 *     module Outer
 *       include Mixin
 *       include Mixin2
 *     end
 *
 *     Mixin.included_modules   #=> []
 *     Outer.included_modules   #=> [Mixin2, Mixin]
 */

This is not really a language-level change, but a clarification of the existing language/std-library documentation.

See proposal