Why does Scalaz show up in my project's API docs?

Question

Suppose my entire project configuration is this simple build.sbt:

scalaVersion := "2.11.4"

libraryDependencies += "org.scalaz" %% "scalaz-core" % "7.1.0"

And this is my code:

import scalaz.Equal
import scalaz.syntax.equal._

object Foo {
  def whatever[A: Equal](a: A, b: A) = a === b
}

Now when I run sbt doc and open the API docs in the browser, I see the scalaz package in the ScalaDoc root package listing, together with my Foo:

object Foo
package scalaz

Or, in case you don't believe me:

I've noticed this with Scalaz before, and I'm not the only one it happens to (see for example the currently published version of the Argonaut API docs). I'm not sure I've seen it happen with any library other than Scalaz.

If I don't actually use anything from Scalaz in my project code, it doesn't show up. The same thing happens on at least 2.10.4 and 2.11.4.

Why is the scalaz package showing up here and how can I make it stop?

Answer 1

I noticed this too. It also happens with the akka.pattern package from Akka as well as for example the upickle package from the upickle project.

Those three packages have two things in common:

1. They are package objects
2. They define at least one type in a mixin trait.

So I did a little experiment with two projects:

Project A:

trait SomeFunctionality {
  class P(val s: String)
}

package object projectA extends SomeFunctionality

Project B (depends on Project A):

package projectB
import projectA._

object B extends App {
  val p = new P("Test")
}

And voila: in the ScalaDoc of Project B appear two packages in the root package:

projectA
projectB

It seems like both criteria above have to be met, since eliminating one solves the issue.

I believe this is a bug in the scala compiler. So I can not help you with avoiding this since the only way would be to change the sources of scalaz in this case. Changing anything in ProjectB except for removing all references to ProjectA didn't help.

---

Update: It seems like you can instruct the compiler to exclude specific packages from scaladoc.

scaladoc -skip-packages <pack1>:<pack2>:...:<packN> files.scala

So this would be a workaround here