Improve Dokka documentation generation

com-lihaoyi · Nov 2, 2024 · 0337126 · 0337126
1 parent 9c3a434
commit 0337126
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 5 deletions.
diff --git a/kotlinlib/src/mill/kotlinlib/KotlinModule.scala b/kotlinlib/src/mill/kotlinlib/KotlinModule.scala
@@ -159,12 +159,24 @@ trait KotlinModule extends JavaModule { outer =>
         // `;` separator is used on all platforms!
         dokkaPluginsClasspath().map(_.path).mkString(";")
       )
+      val depClasspath = (compileClasspath() ++ runClasspath())
+        .filter(p => os.exists(p.path))
+        .map(_.path.toString()).mkString(";")
 
-      // TODO need to provide source sets for the module deps
+      // TODO need to provide a dedicated source set for common sources in case of Multiplatform
+      // platforms supported: jvm, js, wasm, native, common
       val options = dokkaOptions() ++
         Seq("-outputDir", dokkaDir.toString()) ++
         pluginClasspathOption ++
-        docSources().flatMap(pathRef => Seq("-sourceSet", s"-src ${pathRef.path}"))
+        Seq(
+          s"-sourceSet",
+          Seq(
+            s"-src ${docSources().map(_.path).mkString(";")}",
+            s"-displayName $dokkaSourceSetDisplayName",
+            s"-classpath $depClasspath",
+            s"-analysisPlatform $dokkaAnalysisPlatform"
+          ).mkString(" ")
+        )
 
       T.log.info("dokka options: " + options)
 
@@ -215,6 +227,9 @@ trait KotlinModule extends JavaModule { outer =>
     )
   }
 
+  protected def dokkaAnalysisPlatform: String = "jvm"
+  protected def dokkaSourceSetDisplayName: String = "jvm"
+
   protected def when(cond: Boolean)(args: String*): Seq[String] = if (cond) args else Seq()
 
   /**
@@ -269,8 +284,7 @@ trait KotlinModule extends JavaModule { outer =>
             compileCp.iterator.mkString(File.pathSeparator)
           ),
           when(explicitApi())(
-            "-Xexplicit-api",
-            "strict"
+            "-Xexplicit-api=strict"
           ),
           kotlincOptions(),
           extraKotlinArgs,

diff --git a/kotlinlib/src/mill/kotlinlib/js/KotlinJsModule.scala b/kotlinlib/src/mill/kotlinlib/js/KotlinJsModule.scala
@@ -246,6 +246,9 @@ trait KotlinJsModule extends KotlinModule { outer =>
 
   // region private
 
+  protected override def dokkaAnalysisPlatform = "js"
+  protected override def dokkaSourceSetDisplayName = "js"
+
   private[kotlinlib] def kotlinJsCompile(
       outputMode: OutputMode,
       allKotlinSourceFiles: Seq[PathRef],
@@ -365,7 +368,7 @@ trait KotlinJsModule extends KotlinModule { outer =>
       case None => Seq.empty
     })
     if (explicitApi) {
-      innerCompilerArgs ++= Seq("-Xexplicit-api", "strict")
+      innerCompilerArgs ++= Seq("-Xexplicit-api=strict")
     }
 
     val compilerArgs: Seq[String] = Seq(