Cleanups in Java docs and user experience

docs/modules/ROOT/pages/Intro_to_Mill_for_Java.adoc

@@ -18,9 +18,21 @@
 {mill-github-url}[Mill] is your shiny new Java build tool! Mill aims for
 simplicity by reusing concepts you are already familiar with, borrowing ideas
 from modern tools like https://maven.apache.org/[Maven], https://gradle.org/[Gradle],
-https://bazel.build/[Bazel] and https://www.scala-sbt.org/[SBT]. It lets you build
+https://bazel.build/[Bazel]. Mill lets you build and customize
 your projects in a way that's simple, fast, and predictable.
 
+Mill automates dealing with a lot of common build-tool concerns such as caching,
+incremental re-computation, and parallelism. This allows you
+to focus your effort on the business logic unique to your build, while letting
+Mill take care of all the rest.
+
+Compared to Maven and Gradle, Mill builds are far more intuitive and easy to read,
+write, and debug:
+
+* **Mill builds are an order of magnitude more concise than Maven pom.xml files**: this makes
+  them both easy to write and easy to read at a glance
+
+
 include::partial$Intro_to_Mill_Header.adoc[]
 
 

docs/modules/ROOT/pages/Intro_to_Mill_for_Scala.adoc

@@ -22,8 +22,34 @@ from modern tools like https://maven.apache.org/[Maven], https://gradle.org/[Gra
 https://bazel.build/[Bazel] and https://www.scala-sbt.org/[SBT]. It lets you build
 your projects in a way that's simple, fast, and predictable.
 
+
+{mill-github-url}[Mill] is your shiny new Scala build tool! Mill aims for
+simplicity by reusing concepts you are already familiar with, borrowing ideas
+from modern tools like https://maven.apache.org/[Maven], https://gradle.org/[Gradle],
+https://bazel.build/[Bazel] and https://www.scala-sbt.org/[SBT]. Mill lets you build
+and customize your projects in a way that's simple, fast, and predictable.
+
+Mill automates dealing with a lot of common build-tool concerns such as caching,
+incremental re-computation, and parallelism. This allows you
+to focus your effort on the business logic unique to your build, while letting
+Mill take care of all the rest.
+
+Compared to SBT and other tools, Mill builds are far more intuitive and easy to read,
+write, and debug:
+
 include::partial$Intro_to_Mill_Header.adoc[]
 
+The following blog posts discuss some of the fundamental design issues with SBT, and
+how Mill attempts to do better:
+
+- https://www.lihaoyi.com/post/SowhatswrongwithSBT.html[So, what's wrong with SBT?]
+- https://www.lihaoyi.com/post/MillBetterScalaBuilds.html[Mill: Better Scala Builds]
+
+If you are using Mill, you will find the following book by the Author useful in
+using Mill and its supporting libraries to the fullest:
+
+* https://handsonscala.com/[Hands-on Scala Programming]
+
 
 If you are using Mill, you will find the following book by the Author useful in
 using Mill and its supporting libraries to the fullest:

docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc

@@ -1,25 +1,26 @@
 
-Mill automates dealing with a lot of common build-tool concerns: Caching,
-incremental re-computation, parallelism, discoverability, etc. This allows you
-to focus your effort on the business logic unique to your build, while letting
-Mill take care of all the rest.
 
-Mill has built-in support for the Java and https://www.scala-lang.org/[Scala]
-programming language, and can serve as a replacement for
-https://maven.apache.org/[Maven], https://gradle.org/[Gradle], or
-http://www.scala-sbt.org/[SBT]. It can be xref:Extending_Mill.adoc[extended]
-to support any other language or platform via modules (written in Java
-or Scala) or through external subprocesses. Mill supports a rich ecosystem of
+* **Mill builds are easy to extend by non-experts**: anyone can extend a Mill build
+with a few lines of code, without needing to learn a complicated plugin framework,
+allowing end users the freedom to fit their build logic to their own unique requirements
+
+* **Mill builds are familiar to anyone who knows programming**: rather than scopes, lifecycles,
+or phases, Mill builds on top of objects, methods, inheritance, and overrides: concepts
+immediately familiar to any Java programmer
+
+Mill can be xref:Extending_Mill.adoc[extended]
+to support any other language or platform via modules or through
+external subprocesses. Mill supports a rich ecosystem of
 xref:Contrib_Plugins.adoc[] and xref:Thirdparty_Plugins.adoc[].
 
 If you prefer a video introduction rather than text, the following presentation
 (and companion blog post) is a good introduction into what the Mill build tool is
 all about:
 
 - https://www.youtube.com/watch?v=UsXgCeU-ovI&list=PLLMLOC3WM2r6ZFhFfVH74W-sl8LfWtOEc&index=15[Video: A Deep Dive into the Mill Build Tool]
-- https://www.lihaoyi.com/post/SoWhatsSoSpecialAboutTheMillScalaBuildTool.html[Blog Post: So, What's So Special About The Mill Scala Build Tool?]
+- https://www.lihaoyi.com/post/SoWhatsSoSpecialAboutTheMillScalaBuildTool.html[Blog Post: What's So Special About The Mill Scala Build Tool?]
 
 The rest of this page contains a quick introduction to getting start with using
-Mill to build a simple Scala program. The other pages of this doc-site go into
+Mill to build a simple program. The other pages of this doc-site go into
 more depth, with more examples of how to use Mill and more details of how the
 Mill build tool works.

example/basicjava/1-simple/build.sc

@@ -8,7 +8,7 @@ object foo extends RootModule with JavaModule {
     ivy"org.apache.commons:commons-text:1.12.0"
   )
 
-  object test extends JavaModuleTests with TestModule.Junit4{
+  object test extends JavaTests with TestModule.Junit4{
     def ivyDeps = super.ivyDeps() ++ Agg(
       ivy"com.google.guava:guava:33.2.1-jre"
     )

example/basicjava/1-simple/test/src/FooTest.java

@@ -1,5 +1,6 @@
 package foo;
 import static org.junit.Assert.assertEquals;
+import static com.google.common.html.HtmlEscapers.htmlEscaper;
 import org.junit.Test;
 
 public class FooTest {
@@ -10,6 +11,6 @@ public void testSimple() {
 
     @Test
     public void testEscaping() {
-        assertEquals(Foo.generateHtml("<hello>"),  "<h1>&lt;hello&gt;</h1>");
+        assertEquals(Foo.generateHtml("<hello>"),  "<h1>" + htmlEscaper().escape("<hello>") + "</h1>");
     }
 }

example/basicjava/3-multi-module/build.sc

@@ -3,7 +3,7 @@
 import mill._, javalib._
 
 trait MyModule extends JavaModule{
-  object test extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
 }
 
 object foo extends MyModule{

example/basicjava/4-builtin-commands/build.sc

@@ -2,7 +2,7 @@
 import mill._, javalib._
 
 trait MyModule extends JavaModule{
-  object test extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
 }
 
 object foo extends MyModule{

example/javabuilds/5-test-suite/build.sc

@@ -2,7 +2,7 @@
 import mill._, javalib._
 
 object foo extends JavaModule {
-  object test extends JavaModuleTests {
+  object test extends JavaTests {
     def testFramework = "com.novocode.junit.JUnitFramework"
     def ivyDeps = T {
       super.ivyDeps() ++ Agg(ivy"com.novocode:junit-interface:0.11")
@@ -13,11 +13,11 @@ object foo extends JavaModule {
 //// SNIPPET:BUILD2
 
 object bar extends JavaModule {
-  object test extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
 }
 
 //// SNIPPET:BUILD3
 object qux extends JavaModule {
-  object test extends JavaModuleTests with TestModule.Junit4
-  object integration extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
+  object integration extends JavaTests with TestModule.Junit4
 }

example/javabuilds/8-compat-modules/build.sc

@@ -2,7 +2,7 @@
 import mill._, javalib._
 
 object foo extends MavenModule {
-  object test extends MavenModuleTests with TestModule.Junit4
+  object test extends MavenTests with TestModule.Junit4
 }
 
 

example/javabuilds/9-realistic/build.sc

@@ -15,7 +15,7 @@ trait MyModule extends JavaModule with PublishModule {
 
   def ivyDeps = Agg(ivy"org.apache.commons:commons-text:1.12.0")
 
-  object test extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
 }
 
 object foo extends MyModule {

example/javamodule/4-test-deps/build.sc

@@ -5,12 +5,12 @@ import mill._, javalib._
 object qux extends JavaModule {
   def moduleDeps = Seq(baz)
 
-  object test extends JavaModuleTests with TestModule.Junit4 {
+  object test extends JavaTests with TestModule.Junit4 {
     def moduleDeps = super.moduleDeps ++ Seq(baz.test)
   }
 }
 
 
 object baz extends JavaModule {
-  object test extends JavaModuleTests with TestModule.Junit4
+  object test extends JavaTests with TestModule.Junit4
 }

example/scalabuilds/8-compat-modules/build.sc

@@ -3,7 +3,7 @@ import mill._, scalalib._
 
 object foo extends SbtModule {
   def scalaVersion = "2.13.8"
-  object test extends SbtModuleTests {
+  object test extends SbtTests {
     def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.7.11")
     def testFramework = "utest.runner.Framework"
   }
@@ -12,7 +12,7 @@ object foo extends SbtModule {
 
 object bar extends Cross[BarModule]("2.12.17", "2.13.8")
 trait BarModule extends CrossSbtModule {
-  object test extends CrossSbtModuleTests {
+  object test extends CrossSbtTests {
     def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.7.11")
     def testFramework = "utest.runner.Framework"
   }

example/thirdparty/commons-io/build.sc

@@ -14,7 +14,7 @@ object commonsio extends RootModule with PublishModule with MavenModule {
     developers = Nil
   )
 
-  object test extends MavenModuleTests with TestModule.Junit5 with  JmhModule{
+  object test extends MavenTests with TestModule.Junit5 with  JmhModule{
     def jmhCoreVersion = "1.37"
     def ivyDeps = super.ivyDeps() ++ Agg(
       ivy"org.junit.jupiter:junit-jupiter:5.10.3",

example/thirdparty/jimfs/build.sc

@@ -28,7 +28,7 @@ object jimfs extends PublishModule with MavenModule {
 
   def javacOptions = Seq("-processor", "com.google.auto.service.processor.AutoServiceProcessor")
 
-  object test extends MavenModuleTests {
+  object test extends MavenTests {
     def ivyDeps = sharedCompileIvyDeps() ++ Agg(
       ivy"junit:junit:4.13.2",
       ivy"com.google.guava:guava-testlib:31.1-android",

integration/feature/docannotations/repo/build.sc

@@ -16,7 +16,7 @@ trait JUnitTests extends TestModule.Junit4 {
  * The Core Module Docz!
  */
 object core extends JavaModule {
-  object test extends JavaModuleTests with JUnitTests
+  object test extends JavaTests with JUnitTests
 
   /**
    * Core Target Docz!

integration/feature/subprocess-stdout/test/src/SubprocessStdoutTests.scala

@@ -70,15 +70,15 @@ object SubprocessStdoutTests extends IntegrationTestSuite {
           )
         )
       } else {
-        // Note that it should be out of order, because both `print`s will be captured and logged first,
+        // Note that it may be out of order, because both `print`s will be captured and logged first,
         // whereas the two `proc` outputs will get sent to their respective log files and only noticed
         // a few milliseconds later as the files are polled for updates
         assert(
-          res2.contains(
-            """print stdoutRaw
-              |print stderrRaw
-              |proc stdoutRaw
-              |proc stderrRaw""".stripMargin
+          """print stdoutRaw
+            |print stderrRaw
+            |proc stdoutRaw
+            |proc stderrRaw""".stripMargin.linesIterator.toSet.subsetOf(
+            res2.linesIterator.toSet
           )
         )
       }

scalalib/src/mill/scalalib/CrossSbtModule.scala

@@ -11,6 +11,9 @@ trait CrossSbtModule extends SbtModule with CrossModuleBase { outer =>
       PathRef(millSourcePath / "src" / "main" / s"scala-$s")
     )
   }
+
+  type CrossSbtTests = CrossSbtModuleTests
+  @deprecated("Use CrossSbtTests instead", since = "Mill 0.11.10")
   trait CrossSbtModuleTests extends SbtModuleTests {
     override def millSourcePath = outer.millSourcePath
     override def sources = T.sources {

scalalib/src/mill/scalalib/JavaModule.scala

@@ -36,7 +36,8 @@ trait JavaModule
     with SemanticDbJavaModule { outer =>
 
   def zincWorker: ModuleRef[ZincWorkerModule] = super.zincWorker
-
+  type JavaTests = JavaModuleTests
+  @deprecated("Use JavaTests instead", since = "Mill 0.11.10")
   trait JavaModuleTests extends JavaModule with TestModule {
     // Run some consistence checks
     hierarchyChecks()

scalalib/src/mill/scalalib/MavenModule.scala

@@ -16,6 +16,8 @@ trait MavenModule extends JavaModule { outer =>
     millSourcePath / "src" / "main" / "resources"
   }
 
+  type MavenTests = MavenModuleTests
+  @deprecated("Use JavaTests instead", since = "Mill 0.11.10")
   trait MavenModuleTests extends JavaModuleTests {
     override def millSourcePath = outer.millSourcePath
     override def intellijModulePath: os.Path = outer.millSourcePath / "src" / "test"

scalalib/src/mill/scalalib/RunModule.scala

@@ -158,7 +158,7 @@ trait RunModule extends WithZincWorker {
         runUseArgsFile = runUseArgsFile(),
         backgroundOutputs = backgroundOutputs(T.dest)
       )(args().value: _*)(T.ctx())
-      
+
       // Make sure to sleep a bit in the Mill test suite to allow the servers we
       // start time to initialize before we proceed with the following commands
       if (T.env.contains("MILL_TEST_SUITE")) {

scalalib/src/mill/scalalib/SbtModule.scala

@@ -12,7 +12,9 @@ trait SbtModule extends ScalaModule with MavenModule {
     millSourcePath / "src" / "main" / "java"
   )
 
-  trait SbtModuleTests extends ScalaTests with MavenModuleTests {
+  type SbtTests = SbtModuleTests
+  @deprecated("Use SbtTests instead", since = "Mill 0.11.10")
+  trait SbtModuleTests extends ScalaTests with MavenTests {
     override def sources = T.sources(
       millSourcePath / "src" / "test" / "scala",
       millSourcePath / "src" / "test" / "java"