Generate documentation for mixed Java + Scala projects

[charpov]

In a mixed Java + Scala 3 project, scaladoc uses tasty files and ignores all Java sources. How do I make docJar include documentation for Java as well? Is this a matter of using unidoc?

Note that, in my project, all Scala classes are private. So, I only care to document the Java classes. I've set up the project as a Scala module (using override def artifactSuffix = "" to get the right publishing name), but maybe it should somehow be defined as a Java module that uses Scala (and thus would use javadoc instead of scaladoc to generate the documentation)? I don't care much whether the documentation uses scaladoc or javadoc.

[lefou]

AFAIK, there is currently no way to include Javadoc in Scaladoc. (We also have this issue in Mill itself, #5927) There exists a tool genjavadoc that can generate Javadoc from Scala files, but it might be limited.

If you're only interested in the Javadoc, you can override the docJar task to either:

1. just return the super[JavaModule].docJar() result or

2. implement it by packaging the result of javadocGenerated task into a jar. Basically copy and paste these lines:

   mill/libs/javalib/src/mill/javalib/JavaModule.scala

   Lines 1377 to 1379 in db82653

   	def docJar: T[PathRef] = Task[PathRef] {
   	PathRef(Jvm.createJar(Task.dest / "out.jar", Seq(javadocGenerated().path)))
   	}

[charpov]

I had a customized doc task in my old sbt setup, but I was hoping for something simpler with Mill...

Going this route, I still face a several difficulties:

1. javadoc needs the Java sources (while scalaDoc uses the tasty files); easily solved with: override def docSources = allSources().
2. javadoc needs the bytecode for the Scala code: I need to somehow add out/compile.dest/classes to the classpath.
3. javadocGenerated needs to run compile as a dependency to generate this bytecode.

I'll try to hack something, but I could still use some help on tasks 2 and 3.

[charpov]

I solved 2 by adding a link to out/compile.dest/classes inside compile-resources and I ignored 3 since I only care about docJar running within publish. A bit hacky, but good enough for my needs.