Documentation Review for javalib/kotlinlib/scalalib/fundamentals/exte…

…nding/depth (#3734)

Did a once-through reading of most of the documentation site, with the
exception of `scalalib/intro.html` and the three in `comparisons/` which
will need a deeper review

Fixes #3493

build.mill

@@ -329,9 +329,9 @@ trait MillJavaModule extends JavaModule {
   def testDepPaths = Task { upstreamAssemblyClasspath() ++ Seq(compile().classes) ++ resources() }
 
   def testTransitiveDeps: T[Map[String, String]] = Task {
-    val upstream = T.traverse(moduleDeps ++ compileModuleDeps) {
+    val upstream = Task.traverse(moduleDeps ++ compileModuleDeps) {
       case m: MillJavaModule => m.testTransitiveDeps.map(Some(_))
-      case _ => T.task(None)
+      case _ => Task.Anon(None)
     }().flatten.flatten
     val current = Seq(testDep())
     upstream.toMap ++ current
@@ -342,28 +342,28 @@ trait MillJavaModule extends JavaModule {
     if (this == build.main) Seq(build.main)
     else Seq(this, build.main.test)
 
-  def writeLocalTestOverrides = T.task {
+  def writeLocalTestOverrides = Task.Anon {
     for ((k, v) <- testTransitiveDeps()) {
-      os.write(T.dest / "mill" / "local-test-overrides" / k, v, createFolders = true)
+      os.write(Task.dest / "mill" / "local-test-overrides" / k, v, createFolders = true)
     }
-    Seq(PathRef(T.dest))
+    Seq(PathRef(Task.dest))
   }
 
   def runClasspath = super.runClasspath() ++ writeLocalTestOverrides()
 
-  def repositoriesTask = T.task {
+  def repositoriesTask = Task.Anon {
     super.repositoriesTask() ++
       Seq(MavenRepository("https://oss.sonatype.org/content/repositories/releases"))
   }
 
-  def mapDependencies: Task[coursier.Dependency => coursier.Dependency] = T.task {
+  def mapDependencies: Task[coursier.Dependency => coursier.Dependency] = Task.Anon {
     super.mapDependencies().andThen { dep =>
       forcedVersions.find(f =>
         f.dep.module.organization.value == dep.module.organization.value &&
           f.dep.module.name.value == dep.module.name.value
       ).map { forced =>
         val newDep = dep.withVersion(forced.dep.version)
-        T.log.debug(s"Forcing version of ${dep.module} from ${dep.version} to ${newDep.version}")
+        Task.log.debug(s"Forcing version of ${dep.module} from ${dep.version} to ${newDep.version}")
         newDep
       }.getOrElse(dep)
     }
@@ -589,9 +589,9 @@ trait BridgeModule extends MillPublishJavaModule with CrossScalaModule {
     ivy"org.scala-lang:scala-compiler:${crossScalaVersion}"
   )
 
-  def resources = T.sources {
-    os.copy(generatedSources().head.path / "META-INF", T.dest / "META-INF")
-    Seq(PathRef(T.dest))
+  def resources = Task.Sources {
+    os.copy(generatedSources().head.path / "META-INF", Task.dest / "META-INF")
+    Seq(PathRef(Task.dest))
   }
 
   def compilerBridgeIvyDeps: T[Agg[Dep]] = Agg(
@@ -600,18 +600,18 @@ trait BridgeModule extends MillPublishJavaModule with CrossScalaModule {
 
   def compilerBridgeSourceJars: T[Agg[PathRef]] = Task {
     resolveDeps(
-      T.task { compilerBridgeIvyDeps().map(bindDependency()) },
+      Task.Anon { compilerBridgeIvyDeps().map(bindDependency()) },
       sources = true
     )()
   }
 
   def generatedSources = Task {
 
     compilerBridgeSourceJars().foreach { jar =>
-      os.unzip(jar.path, T.dest)
+      os.unzip(jar.path, Task.dest)
     }
 
-    Seq(PathRef(T.dest))
+    Seq(PathRef(Task.dest))
   }
 }
 
@@ -752,7 +752,7 @@ object idea extends MillPublishScalaModule {
  */
 object dist0 extends MillPublishJavaModule {
   // disable scalafix here because it crashes when a module has no sources
-  def fix(args: String*): Command[Unit] = T.command {}
+  def fix(args: String*): Command[Unit] = Task.Command {}
   def moduleDeps = Seq(build.runner, idea)
 
   def testTransitiveDeps = build.runner.testTransitiveDeps() ++ Seq(
@@ -779,7 +779,7 @@ object dist extends MillPublishJavaModule {
     (s"com.lihaoyi-${dist.artifactId()}", dist0.runClasspath().map(_.path).mkString("\n"))
   )
 
-  def genTask(m: ScalaModule) = T.task { Seq(m.jar(), m.sourceJar()) ++ m.runClasspath() }
+  def genTask(m: ScalaModule) = Task.Anon { Seq(m.jar(), m.sourceJar()) ++ m.runClasspath() }
 
   def forkArgs: T[Seq[String]] = Task {
     val genIdeaArgs =
@@ -801,7 +801,7 @@ object dist extends MillPublishJavaModule {
 
   def launcher = Task {
     val isWin = scala.util.Properties.isWin
-    val outputPath = T.dest / (if (isWin) "run.bat" else "run")
+    val outputPath = Task.dest / (if (isWin) "run.bat" else "run")
 
     os.write(outputPath, prependShellScript())
     if (!isWin) os.perms.set(outputPath, "rwxrwxrwx")
@@ -840,22 +840,22 @@ object dist extends MillPublishJavaModule {
         prependShellScript = launcherScript(shellArgs, cmdArgs, Agg("$0"), Agg("%~dpnx0")),
         assemblyRules = assemblyRules
       ).path,
-      T.dest / filename
+      Task.dest / filename
     )
-    PathRef(T.dest / filename)
+    PathRef(Task.dest / filename)
   }
   def assembly = Task {
-    T.traverse(allPublishModules)(m => m.publishLocalCached)()
+    Task.traverse(allPublishModules)(m => m.publishLocalCached)()
     val raw = rawAssembly().path
-    os.copy(raw, T.dest / raw.last)
-    PathRef(T.dest / raw.last)
+    os.copy(raw, Task.dest / raw.last)
+    PathRef(Task.dest / raw.last)
   }
 
   def prependShellScript = Task {
     val (millArgs, otherArgs) =
       forkArgs().partition(arg => arg.startsWith("-DMILL") && !arg.startsWith("-DMILL_VERSION"))
     // Pass Mill options via file, due to small max args limit in Windows
-    val vmOptionsFile = T.dest / "mill.properties"
+    val vmOptionsFile = Task.dest / "mill.properties"
     val millOptionsContent =
       millArgs.map(_.drop(2).replace("\\", "/")).mkString(
         "\r\n"
@@ -890,11 +890,11 @@ object dist extends MillPublishJavaModule {
     Jvm.createJar(Agg(), JarManifest(manifestEntries))
   }
 
-  def run(args: Task[Args] = T.task(Args())) = Task.Command(exclusive = true) {
+  def run(args: Task[Args] = Task.Anon(Args())) = Task.Command(exclusive = true) {
     args().value match {
       case Nil => mill.api.Result.Failure("Need to pass in cwd as first argument to dev.run")
       case wd0 +: rest =>
-        val wd = os.Path(wd0, T.workspace)
+        val wd = os.Path(wd0, Task.workspace)
         os.makeDir.all(wd)
         try {
           Jvm.runSubprocess(
@@ -918,32 +918,32 @@ object dist extends MillPublishJavaModule {
  * @param ivyRepo The local Ivy repository where Mill modules should be published to
  */
 def installLocal(binFile: String = DefaultLocalMillReleasePath, ivyRepo: String = null) =
-  T.command {
-    PathRef(installLocalTask(T.task(binFile), ivyRepo)())
+  Task.Command {
+    PathRef(installLocalTask(Task.Anon(binFile), ivyRepo)())
   }
 
-def installLocalCache() = T.command {
+def installLocalCache() = Task.Command {
   val path = installLocalTask(
-    T.task((os.home / ".cache" / "mill" / "download" / millVersion()).toString())
+    Task.Anon((os.home / ".cache" / "mill" / "download" / millVersion()).toString())
   )()
-  T.log.outputStream.println(path.toString())
+  Task.log.outputStream.println(path.toString())
   PathRef(path)
 }
 
-def installLocalTask(binFile: Task[String], ivyRepo: String = null): Task[os.Path] = T.task {
+def installLocalTask(binFile: Task[String], ivyRepo: String = null): Task[os.Path] = Task.Anon {
   val millBin = dist.assembly()
-  val targetFile = os.Path(binFile(), T.workspace)
+  val targetFile = os.Path(binFile(), Task.workspace)
   if (os.exists(targetFile))
-    T.log.info(s"Overwriting existing local Mill binary at ${targetFile}")
+    Task.log.info(s"Overwriting existing local Mill binary at ${targetFile}")
   os.copy.over(millBin.path, targetFile, createFolders = true)
-  T.log.info(s"Published ${dist.allPublishModules.size} modules and installed ${targetFile}")
+  Task.log.info(s"Published ${dist.allPublishModules.size} modules and installed ${targetFile}")
   targetFile
 }
 
-def millBootstrap = T.sources(T.workspace / "mill")
+def millBootstrap = Task.Sources(Task.workspace / "mill")
 
 def bootstrapLauncher = Task {
-  val outputPath = T.dest / "mill"
+  val outputPath = Task.dest / "mill"
   val millBootstrapGrepPrefix = "(\n *DEFAULT_MILL_VERSION=)"
   val millDownloadUrlPrefix = "(\n *MILL_DOWNLOAD_URL=)"
 
@@ -959,12 +959,12 @@ def bootstrapLauncher = Task {
   PathRef(outputPath)
 }
 
-def examplePathsWithArtifactName:Task[Seq[(os.Path,String)]] = T.task{
+def examplePathsWithArtifactName:Task[Seq[(os.Path,String)]] = Task.Anon{
   for {
     exampleMod <- build.example.exampleModules
     path = exampleMod.millSourcePath
   } yield {
-    val example = path.subRelativeTo(T.workspace)
+    val example = path.subRelativeTo(Task.workspace)
     val artifactName = millVersion() + "-" + example.segments.mkString("-")
     (path, artifactName)
   }
@@ -973,16 +973,16 @@ def examplePathsWithArtifactName:Task[Seq[(os.Path,String)]] = T.task{
 
 def exampleZips: T[Seq[PathRef]] = Task {
   examplePathsWithArtifactName().map{ case (examplePath, exampleStr) =>
-    os.copy(examplePath, T.dest / exampleStr, createFolders = true)
-    os.write(T.dest / exampleStr / ".mill-version", millLastTag())
-    os.copy(bootstrapLauncher().path, T.dest / exampleStr / "mill")
-    val zip = T.dest / s"$exampleStr.zip"
-    os.proc("zip", "-r", zip, exampleStr).call(cwd = T.dest)
+    os.copy(examplePath, Task.dest / exampleStr, createFolders = true)
+    os.write(Task.dest / exampleStr / ".mill-version", millLastTag())
+    os.copy(bootstrapLauncher().path, Task.dest / exampleStr / "mill")
+    val zip = Task.dest / s"$exampleStr.zip"
+    os.proc("zip", "-r", zip, exampleStr).call(cwd = Task.dest)
     PathRef(zip)
   }
 }
 
-def uploadToGithub(authKey: String) = T.command {
+def uploadToGithub(authKey: String) = Task.Command {
   val vcsState = VcsVersion.vcsState()
   val label = vcsState.format()
   if (label != millVersion()) sys.error("Modified mill version detected, aborting upload")
@@ -1030,8 +1030,8 @@ def validate(): Command[Unit] = {
   val tasks = resolveTasks("__.compile", "__.minaReportBinaryIssues")
   val sources = resolveTasks("__.sources")
 
-  T.command {
-    T.sequence(tasks)()
+  Task.Command {
+    Task.sequence(tasks)()
     mill.scalalib.scalafmt.ScalafmtModule.checkFormatAll(Tasks(sources))()
     build.docs.localPages()
     ()

contrib/scalapblib/readme.adoc

@@ -78,6 +78,6 @@ object example extends ScalaPBModule {
   def scalaVersion = "2.12.6"
   def scalaPBVersion = "0.7.4"
   override def scalaPBAdditionalArgs =
-    Seq(s"--zio_out=${T.dest.toIO.getCanonicalPath}")
+    Seq(s"--zio_out=${Task.dest.toIO.getCanonicalPath}")
 }
 ----

docs/modules/ROOT/nav.adoc

@@ -61,8 +61,7 @@
 // either section above, it is probably an important enough topic it is worth
 // breaking out on its own
 .Extending Mill
-* xref:extending/import-ivy.adoc[]
-* xref:extending/using-plugins.adoc[]
+* xref:extending/import-ivy-plugins.adoc[]
 * xref:extending/contrib-plugins.adoc[]
 // See also the list in Contrib_Plugins.adoc
 ** xref:contrib/artifactory.adoc[]

docs/modules/ROOT/pages/depth/design-principles.adoc

@@ -66,9 +66,9 @@ is what allows us to be aggressive about caching and parallelizing the
 evaluation of build tasks during a build.
 
 Many kinds of build steps do require files on disk, and for that Mill provides
-the `T.dest` folder. This is a folder on disk dedicated to each build task,
+the `Task.dest` folder. This is a folder on disk dedicated to each build task,
 so that it can read and write things to it without worrying about conflicts
-with other tasks that have their own `T.dest` folders. In effect, this makes
+with other tasks that have their own `Task.dest` folders. In effect, this makes
 even file output "pure": we can know precisely where a task's output files
 live when we need to invalidate them, and it allows multiple tasks all
 reading and writing to the filesystem to do so safely even when in parallel.

docs/modules/ROOT/pages/depth/evaluation-model.adoc

@@ -70,10 +70,10 @@ the overall workflow remains fast even for large projects:
 
     * ``Task``s are evaluated in dependency order
 
-    * xref:fundamentals/tasks.adoc#_targets[Target]s only re-evaluate if their input ``Task``s
+    * xref:fundamentals/tasks.adoc#_cached_tasks[Cached Task]s only re-evaluate if their input ``Task``s
      change.
 
-    * xref:fundamentals/tasks.adoc#_persistent_tasks[Task.Persistent]s preserve the `T.dest` folder on disk between runs,
+    * xref:fundamentals/tasks.adoc#_persistent_tasks[Task.Persistent]s preserve the `Task.dest` folder on disk between runs,
       allowing for finer-grained caching than Mill's default task-by-task
       caching and invalidation