Doc & Test Suite tweaks (#4023)

Add some subheadings to break up the large page

Author: lihaoyi

.github/workflows/run-tests.yml

@@ -136,7 +136,7 @@ jobs:
           - java-version: '11'
             millargs: '"{main,scalalib,bsp}.__.testCached"'
           - java-version: '11'
-            millargs: '"example.scalalib.{basic,web}.__.fork.testCached"'
+            millargs: '"example.scalalib.basic.__.fork.testCached"'
           - java-version: 17
             millargs: "'integration.{feature,failure}[_].fork.testCached'"
           - java-version: '11'

docs/modules/ROOT/pages/comparisons/java-compile.adoc

@@ -12,7 +12,7 @@ Doing some ad-hoc benchmarks, we find that although the compiler is blazing fast
 build tools add significant overhead over compiling Java directly:
 
 |===
-| Mockito Core | Time | Compiler lines/s | Multiplier | Netty Common | Time | Compiler lines/s | Multiplier
+| Mockito Core | Time | Compiler lines/s | Slowdown | Netty Common | Time | Compiler lines/s | Slowdown
 | Javac Hot | 0.36s | 115,600 | 1.0x | Javac Hot | 0.29s | 102,500 | 1.0x
 | Javac Cold | 1.29s | 32,200 | 4.4x | Javac Cold | 1.62s | 18,300 | 5.6x
 | Mill | 1.20s | 34,700 | 4.1x | Mill | 1.11s | 26,800 | 3.8x
@@ -275,10 +275,16 @@ $ ./mill clean common; time ./mill common.compile
 1.11s
 ```
 
+These benchmarks are run in similar conditions as those we saw earlier: ad-hoc on my M1
+Macbook Pro, with the metadata and jars of all third-party dependencies already downloaded and
+cached locally. So the time we are seeing above is purely the Java compilation + the overhead
+of the build tool realizing it doesn't need to do anything except compile the Java source code
+using the dependencies we already have on disk.
+
 Tabulating this all together gives us the table we saw at the start of this page:
 
 |===
-| Mockito Core | Time | Compiler lines/s | Multiplier | Netty Common | Time | Compiler lines/s | Multiplier
+| Mockito Core | Time | Compiler lines/s | Slowdown | Netty Common | Time | Compiler lines/s | Slowdown
 | Javac Hot | 0.36s | 115,600 | 1.0x | Javac Hot | 0.29s | 102,500 | 1.0x
 | Javac Cold | 1.29s | 32,200 | 4.4x | Javac Cold | 1.62s | 18,300 | 5.6x
 | Mill | 1.20s | 34,700 | 4.1x | Mill | 1.11s | 26,800 | 3.8x

docs/modules/ROOT/pages/index.adoc

@@ -15,7 +15,7 @@ helps keep builds clean and understandable
 * Mill is an easier alternative to https://bazel.build/[Bazel]
 for xref:depth/large-builds.adoc[large multi-language monorepos] with hundreds of modules
 
-To get started using Mill for projects in each language:
+To get started using Mill, see the language-specific introductory documentation linked below:
 
 [cols="1a,1a,1a"]
 |===
@@ -24,6 +24,8 @@ To get started using Mill for projects in each language:
 | xref:kotlinlib/intro.adoc[image:index/iconscout-kotlin.svg[kotlin,32] Kotlin with Mill]
 |===
 
+=== Why Mill?
+
 Although the Java compiler is very fast and the Java language is easy to learn,
 JVM build tools have a reputation for being sluggish and confusing. Mill tries to
 offer a better alternative, letting your build system take full advantage of the
@@ -72,8 +74,10 @@ https://github.com/com-lihaoyi/Ammonite[Ammonite REPL], and the
 https://github.com/SpinalHDL/SpinalHDL[SpinalHDL] and
 https://github.com/chipsalliance/chisel[Chisel] hardware design frameworks.
 Mill can be used for applications built on top of common JVM frameworks like
-xref:javalib/web-examples.adoc#_spring_boot_todomvc_app[Spring Boot] or
-xref:javalib/web-examples.adoc#_micronaut_todomvc_app[Micronaut].
+Spring Boot (both xref:javalib/web-examples.adoc#_spring_boot_todomvc_app[in Java]
+and xref:kotlinlib/web-examples.adoc#_spring_boot_todomvc_app[in Kotlin]),
+xref:javalib/web-examples.adoc#_micronaut_todomvc_app[Micronaut],
+or xref:kotlinlib/web-examples.adoc#_ktor_todomvc_app[Ktor].
 
 Mill borrows ideas from other tools like https://maven.apache.org/[Maven],
 https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn from the
@@ -88,7 +92,7 @@ build tools, check out these pages:
 | xref:comparisons/sbt.adoc[image:index/sbt.png[sbt,32] Mill vs SBT]
 |===
 
-
+=== Contributing and Community
 
 If you want to contribute to Mill, or are interested in the fundamental ideas behind 
 Mill rather than the user-facing benefits discussed above, check out the page on 
@@ -101,7 +105,7 @@ they are interesting:
 To engage Mill with the community, you can use the channels below:
 
 * https://github.com/com-lihaoyi/mill/discussions[Mill Github Discussions]
-* https://discord.com/invite/scala[Scala Discord], in the TOOLING#mill channel
+* https://discord.com/invite/scala[Scala Discord], in the `TOOLING#mill` channel
 
 Mill maintains an open list of issue bounties below, with payouts ranging from
 500USD to 3000USD per issue. Feel free to look through the list and try your

example/extending/jvmcode/6-module-cached-classloader/bar/src/Bar.java

@@ -1,6 +1,5 @@
 package bar;
 
-import java.io.IOException;
 import java.nio.file.*;
 import java.util.Arrays;
 import java.util.stream.Collectors;
@@ -13,7 +12,8 @@ public class Bar {
   static String mangledText;
   static Path fileDest;
 
-  public static void main(String[] args) throws IOException {
+  public static void main(String[] args) throws Exception {
+    Thread.sleep(1000); // Simulate a slow program that takes some time
     dest = Paths.get(args[0]);
     sources = Arrays.<String>copyOfRange(args, 1, args.length);
     for (String sourceStr : sources) {

main/server/test/src/mill/main/server/ClientServerTests.scala

@@ -172,7 +172,7 @@ object ClientServerTests extends TestSuite {
         // Make sure if we delete the out dir, the server notices and exits
         Thread.sleep(500)
         os.remove.all(res3.outDir)
-        Thread.sleep(500)
+        Thread.sleep(1000)
 
         assert(res3.logsFor("serverId file missing") == Seq("server-1"))
         assert(res3.logsFor("exiting server") == Seq("server-1", "server-1"))