How to force SBT to use Javadoc instead of Scaladoc? - scala

Question

I have Java based a Play & Akka project that is built with SBT, is there any way to tell SBT to run Javadoc instead of Scaladoc when building the project? The SBT documentation says that
“sbt will run javadoc if there are only Java sources in the project. If there are any Scala sources, sbt will run scaladoc.”
and there are no Scala files in the project but Scaladoc is still run. I assume that this is because the Play plugin is converting the view templates and conf/routes file into Scala code before compilation happens.

Answer 1

tl;dr Change sources in (Compile, doc) to exclude *.scala files so scaladoc doesn't kick in.
As you can read below sources in (Compile, doc) holds all sources, both managed and unmanaged in a project:
> inspect compile:doc::sources
[info] Task: scala.collection.Seq[java.io.File]
[info] Description:
[info] All sources, both managed and unmanaged.
With some filtering you can achieve your goal quite easily - use the following in build.sbt:
sources in (Compile, doc) <<= sources in (Compile, doc) map { _.filterNot(_.getName endsWith ".scala") }
A sample project's session (comments with // are mine to enhance reading):
// display current setting's value
> show compile:doc::sources
[info] ArrayBuffer(/Users/jacek/sandbox/sbt-learning-space/src/main/scala/x.scala, /Users/jacek/sandbox/sbt-learning-space/src/main/java/Hello.java)
[success] Total time: 0 s, completed Aug 24, 2014 9:31:34 PM
// generate docs - scaladoc kicks in since there are scala files
> doc
[info] Updating {file:/Users/jacek/sandbox/sbt-learning-space/}sbt-learning-space...
[info] Resolving org.fusesource.jansi#jansi;1.4 ...
[info] Done updating.
[info] Main Scala API documentation to /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api...
model contains 3 documentable templates
[info] Main Scala API documentation successful.
Hello
[success] Total time: 1 s, completed Aug 24, 2014 9:32:15 PM
// change the value of sources in the current session only - use session save to retain it
> set sources in (Compile, doc) <<= sources in (Compile, doc) map { _.filterNot(_.getName endsWith ".scala") }
[info] Defining compile:doc::sources
[info] The new value will be used by compile:doc
[info] Reapplying settings...
[info] Set current project to hello (in build file:/Users/jacek/sandbox/sbt-learning-space/)
// display current setting's value - it only holds the single java file
> show compile:doc::sources
[info] ArrayBuffer(/Users/jacek/sandbox/sbt-learning-space/src/main/java/Hello.java)
[success] Total time: 0 s, completed Aug 24, 2014 9:33:23 PM
// generate docs - javadoc is properly generated
> doc
[info] Main Java API documentation to /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api...
[info] Loading source file /Users/jacek/sandbox/sbt-learning-space/src/main/java/Hello.java...
[info] Constructing Javadoc information...
[info] Standard Doclet version 1.7.0_65
[info] Building tree for all the packages and classes...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/Hello.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/package-frame.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/package-summary.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/package-tree.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/constant-values.html...
[info] Building index for all the packages and classes...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/overview-tree.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/index-all.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/deprecated-list.html...
[info] Building index for all classes...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/allclasses-frame.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/allclasses-noframe.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/index.html...
[info] Generating /Users/jacek/sandbox/sbt-learning-space/target/scala-2.10/api/help-doc.html...
[info] Main Java API documentation successful.
Hello
[success] Total time: 1 s, completed Aug 24, 2014 9:34:01 PM

Answer 2

You could try and integrate genjavadoc into sbt, in order to generate a javadoc.
The ScalaDoc can still be generated using the normal doc task,
whereas the JavaDoc can be generated using genjavadoc:doc.

Answer 3

Another approach, allowed with scala 2.12.0-RC1 (Sept. 2016) and SI 4826 is to let scaladoc run! It will process javadoc comments!
Scaladoc already processes Java sources and produces Scaladoc for them.
It just ignores the doc comments.
Many of our Scala codebases have at least some Java in them for various reasons.
It'd be nice if Scaladoc could generate full documentation for these mixed codebases, including all doc comments.