Add example documentation for ModuleRef

docs/modules/ROOT/pages/fundamentals/modules.adoc

@@ -61,4 +61,6 @@ needing to define your own `Task.Command` in your `build.mill` file
 
 == Aliasing External Modules
 
-include::partial$example/fundamentals/modules/10-external-module-aliases.adoc[]
+include::partial$example/fundamentals/modules/10-external-module-aliases.adoc[]
+
+== Abstract Modules References

example/fundamentals/modules/11-module-ref/bar/src/bar/Bar.java

@@ -0,0 +1,11 @@
+package bar;
+
+
+public class Bar {
+    public static String generateHtml(String text) {
+        String value = "<h1>" + text + "</h1>";
+        return value;
+    }
+
+
+}

example/fundamentals/modules/11-module-ref/bartest/src/bar/BarTests.java

@@ -0,0 +1,13 @@
+package bar;
+
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class BarTests {
+
+    @Test
+    public void simple() {
+        String result = Bar.generateHtml("hello");
+        assertEquals("<h1>hello</h1>", result);
+    }
+}

example/fundamentals/modules/11-module-ref/build.mill

@@ -0,0 +1,38 @@
+// When you define an abstract module, often you are referencing an existing module
+// somewhere in your build. A naive `def upstreamModule: FooModule`
+// would create a module alias, which is often not what you want since the referenced
+// module already has a place in your build hierarchy. In such scenarios, you can use
+// a `ModuleRef(...)` to wrap the abstract module, such that the abstract `def` does
+// not participate in task query resolution:
+
+package build
+import mill._, javalib._
+import mill.define.ModuleRef
+
+object foo extends JavaModule
+object bar extends JavaModule
+
+trait MyTestModule extends JavaModule with TestModule.Junit4{
+  def upstreamModule: ModuleRef[JavaModule]
+
+  def moduleDeps = Seq(upstreamModule())
+}
+
+object footest extends MyTestModule{
+  def upstreamModule = ModuleRef(foo)
+}
+object bartest extends MyTestModule{
+  def upstreamModule = ModuleRef(bar)
+}
+
+
+/** Usage
+
+> mill __.test
+Test foo.FooTests.simple finished, ...
+Test bar.BarTests.simple finished, ...
+...
+
+> mill resolve foo.upstreamModule._ # This fails since it's a `ModuleRef`, not just a `Module`
+error: resolve Cannot resolve foo.upstreamModule...
+*/

example/fundamentals/modules/11-module-ref/foo/src/foo/Foo.java

@@ -0,0 +1,8 @@
+package foo;
+
+
+public class Foo {
+
+    public static final String VALUE = "hello";
+}
+

example/fundamentals/modules/11-module-ref/footest/src/bar/FooTests.java

@@ -0,0 +1,12 @@
+package foo;
+
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class FooTests {
+
+    @Test
+    public void simple() {
+        assertEquals("hello", Foo.VALUE);
+    }
+}