Ian Phillips Ian Phillips - 2 months ago 25
Scala Question

How to force SBT to use Javadoc instead of Scaladoc?

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

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
Comments