Doc review (#5431)

Author: lihaoyi

changelog.adoc

@@ -489,7 +489,7 @@ _2025-05-10_
 
 * fix: Use root qualifier in Discover macro ({link-pr}/5055[#5055])
 * Fix selective execution when multiple changes are made to one module under `--watch` ({link-pr}/5032[#5032])
-* Add ability to define `package` `ExternalModule`s that can be calle via just `pkg.path/` rather than `pkg.path.ObjectName/` ({link-pr}/4920[#4920])
+* Add ability to define `package` ``ExternalModule``s that can be calle via just `pkg.path/` rather than `pkg.path.ObjectName/` ({link-pr}/4920[#4920])
 * Backport `javascriptlib` and `pythonlib` improvements from `main` branch ({link-pr}/4893[#4893])
 * Fix wildcard and type selector query bugs ({link-pr}/4862[#4862])
 * Lots of Mill `main` branch compatibility changes, adding the new name and deprecating the old one
@@ -1418,7 +1418,7 @@ __New features__
 __Fixes and Improvements__
 
 * Better detect Windows Subsystem for Linux environments {link-pr}/2901[#2901]
-* Avoid evaluating `Task.Input`s twice {link-pr}/2952[#2952]
+* Avoid evaluating ``Task.Input``s twice {link-pr}/2952[#2952]
 * Deduplicate (anonymous) tasks in results {link-pr}/2959[#2959]
 * Synchronize `evaluateGroupCached` to avoid concurrent access to cache  {link-pr}/2980[#2980]
 * Properly sanitize Windows reserved names and symbols in evaluator paths {link-pr}/2964[#2964], {link-pr}/2965[#2965]
@@ -2450,7 +2450,7 @@ The API is suspected to change before a 0.10.0 releae.*
 
 _Changes since {prev-version}:_
 
-* `ScalaModule with PublishModule`: the `scala-library` artifact is now always part of the dependencies in published `pom.xml`s and `ivy.xml`s
+* `ScalaModule with PublishModule`: the `scala-library` artifact is now always part of the dependencies in published ``pom.xml``s and `ivy.xml`s
 * New `JavaModule.mandatoryMvnDeps` target to provide essential dependencies like scala-library without forcing the user to call `super.mvnDeps`
 * `ScalaJSModule.scalaLibraryMvnDeps` no longer contains the scala-js-library, but only the scala-library; if you need that, use `ScalaJSModule.mandatoryMvnDeps` instead.
 * `import $ivy` support `$MILL_BIN_PLATFORM` variable and a new sort notations for external plugins
@@ -3280,7 +3280,7 @@ _2018-03-04_
 
 * Speed up Mill client initialization by another 50-100ms
 
-* Speed up incremental `assembly`s in the common case where upstream dependencies do not change.
+* Speed up incremental ``assembly``s in the common case where upstream dependencies do not change.
 
 * Make `ScalaJSModule#run` work with main-method discovery
 

example/depth/sandbox/1-task/build.mill

@@ -1,10 +1,3 @@
-// In order to help manage your build, Mill performs some rudimentary filesystem
-// sandboxing to keep different tasks and modules from interfering with each other.
-// This tries to ensure your tasks only read and write from their designated `.dest/`
-// folders, which are unique to each task and thus guaranteed not to collide with
-// the filesystem operations of other tasks that may be occurring in parallel.
-//
-//
 // === `Task.dest`
 // The standard way of working with a task's `.dest/` folder is through the `Task.dest`
 // property. This is available within any task, and gives you access to the
@@ -24,11 +17,14 @@ object foo extends Module {
 .../out/foo/tDestTask.dest
 */
 
+// If you really need to reference paths outside of the `Task.dest`, you can do
+// so via `BuildCtx.workspaceRoot`.
+
 // === Filesystem Read/Write Checks
 //
 // Mill enforces limits on what you can read and write while a task is executing.
 // In general, a task may only write to its own `Task.dest` folder, and may only
-// read from the `PathRef`s provided to it from upstream tasks
+// read from the ``PathRef``s provided to it from upstream tasks
 
 def bannedWriteTask = Task {
   os.write(BuildCtx.workspaceRoot / "banned-path", "hello")
@@ -63,9 +59,9 @@ error: ...Reading from out/foo/tDestTask.json not allowed during execution of `b
 
 val listed = BuildCtx.watchValue(os.list(BuildCtx.workspaceRoot).map(_.last))
 
-// === Disabling Task Sandboxing
+// === Bypassing Task Sandboxing
 //
-// You can disable Mill's filesystem read/write limitations via
+// You can bypass Mill's filesystem read/write limitations via
 // `BuildCtx.withFilesystemCheckerDisabled`. Note that this bypasses the
 // best-practices that Mill tries to enforce on your tasks and may result in strange
 // bugs around caching, parallelism, and invalidation, so you shouldn't do this unless

example/depth/sandbox/2-test/build.mill

@@ -63,7 +63,7 @@ object bar extends MyModule
 // one another, which helps keep tests stable and deterministic even when run in
 // parallel
 //
-// === Escaping the Test Sandbox
+// === Bypassing the Test Sandbox
 
 // Within a test, you can use the `MILL_WORKSPACE_ROOT` environment variable
 // to access the workspace root directory:
@@ -89,9 +89,7 @@ object qux extends JavaModule {
 */
 
 //
-// === Disabling Test Sandboxing
-//
-// Test sandboxing can be disabled by setting `def testSandboxWorkingDir = false`
+// Test sandboxing can also be disabled by setting `def testSandboxWorkingDir = false`
 // on your test module, which makes your unit tests run in the root of your
 // project workspace, with full access to the project files on disk.
 //

example/extending/jvmcode/1-subprocess/build.mill

@@ -4,7 +4,7 @@
 //
 // * `defaultResolver().classpath` to resolve the dependencies from Maven Central,
 //   converting `org:name:version` coordinates (and their transitive dependencies) to
-//   `PathRef`s referring to files on disk
+//   ``PathRef``s referring to files on disk
 //
 // * `Jvm.runSubprocess`, which runs the given classpath files in a subprocess, starting
 //   from specified `mainClass`

runner/client/package.mill

@@ -12,11 +12,10 @@ import mill.api.BuildCtx
  */
 object `package` extends MillPublishJavaModule with BuildInfo {
   def buildInfoPackageName = "mill.client"
-  def millJvmVersion = Task.Source(BuildCtx.workspaceRoot / ".mill-jvm-version")
 
   def buildInfoMembers = Seq(
     BuildInfo.Value("millVersion", build.millVersion(), "Mill version."),
-    BuildInfo.Value("defaultJvmId", os.read(millJvmVersion().path).trim())
+    BuildInfo.Value("defaultJvmId", os.read(build.millJvmVersion().path).trim())
   )
 
   def moduleDeps = Seq(build.core.constants)