Clarify and document the invalidation logic

Author: eregon

src/main/java/org/truffleruby/core/module/ModuleFields.java

@@ -295,6 +295,8 @@ public void include(RubyContext context, Node currentNode, RubyModule module) {
     private void performIncludes(ModuleChain inclusionPoint, Deque<RubyModule> moduleAncestors) {
         while (!moduleAncestors.isEmpty()) {
             RubyModule mod = moduleAncestors.pop();
+            // Module#include only adds modules between the current class and the super class,
+            // so invalidating the current class is enough as all affected lookups would go through the current class.
             newMethodsVersion(mod.fields.getMethodNames());
             inclusionPoint.insertAfter(mod);
         }
@@ -324,16 +326,11 @@ public void prepend(RubyContext context, Node currentNode, RubyModule module) {
 
         SharedObjects.propagate(context.getLanguageSlow(), rubyModule, module);
 
-        ModuleChain mod = module.fields.start;
-        final ModuleChain topPrependedModule = start.getParentModule();
-
-        final ModuleFields moduleFieldsToInvalidate;
-        if (topPrependedModule != this) {
-            moduleFieldsToInvalidate = topPrependedModule.getActualModule().fields;
-        } else {
-            moduleFieldsToInvalidate = this;
-        }
+        // Previous calls on instances of the current class must have looked up through the first prepended module,
+        // so invalidate that one.
+        final ModuleFields moduleFieldsToInvalidate = getFirstModuleChain().getActualModule().fields;
 
+        ModuleChain mod = module.fields.start;
         ModuleChain cur = start;
         while (mod != null &&
                 !(mod instanceof ModuleFields && ((ModuleFields) mod).rubyModule instanceof RubyClass)) {