module-system.chapter.md: Add mental model to `type` and `extendModules`

1 files changed, 5 insertions, 0 deletions

diff --git a/doc/module-system/module-system.chapter.md b/doc/module-system/module-system.chapter.md
index 2f19096577fd8..2f9716c89dbc6 100644
--- a/doc/module-system/module-system.chapter.md
+++ b/doc/module-system/module-system.chapter.md
@@ -64,12 +64,17 @@ The option definitions that are typed with this type will extend the current set
 
 However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule.
 
+If you're familiar with prototype inheritance, you can think of this `evalModules` invocation as the prototype, and usages of this type as the instances.
+
 This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`.
+<!-- TODO: document the module arguments. Using moduleType is like saying: suppose this configuration was extended. -->
 
 #### `extendModules` {#module-system-lib-evalModules-return-value-extendModules}
 
 A function similar to `evalModules` but building on top of the already passed [`modules`](#module-system-lib-evalModules-param-modules). Its arguments, `modules` and `specialArgs` are added to the existing values.
 
+If you're familiar with prototype inheritance, you can think of the current, actual `evalModules` invocation as the prototype, and the return value of `extendModules` as the instance.
+
 The real work of module evaluation happens while computing the values in `config` and `options`, so multiple invocations of `extendModules` have a particularly small cost, as long as only the final `config` and `options` are evaluated.
 
 If you do reference multiple `config` (or `options`) from before and after `extendModules`, evaluation performance is the same as with multiple `evalModules` invocations, because the new modules' ability to override existing configuration fundamentally requires constructing a new `config` and `options` fixpoint.