Scaladoc: @group tag not showing in API documentation

Question

I'm trying to organise the members of a class in my library API documentation using @groupname and @group tags, but it doesn't work (I'm using sbt 0.13.11)

My toy build.sbt:

name := "test"
scalaVersion := "2.10.5"

My toy code src/main/scala/test.scala:

package test
/** Test class
 *
 * @groupname print Printer
 * @groupname throw Thrower
 */
class TestClass {
  /** @group print */
  def trivialPrint: Unit = print("Hello")
  /** @group throw */
  def trivialError: Unit = throw new Exception("Hello")
}

sbt doc compiles an API doc where both my functions are in the "Value Members" group of the class (cf. screenshot). What am I doing wrong?

Hydrophone

Answer 1

Prior to Scala 2.11 you have to explicitly ask for Scaladoc grouping support in your build.sbt:

name := "test"
scalaVersion := "2.10.5"
scalacOptions += "-groups"

You could scope it to in (Compile, doc), but I'm not sure it matters much.

Like most things related to Scaladoc this is essentially undocumented, but it works.

Morganite

Nice, thanks a lot. I was a bit afraid that the answer would be RTFM, so I'm doubly satisfied. Is there an easy way to discover undocumented features though? Google failed me on this one... – Hydrophone

Answer 2

At least for Scala 2.11.x, it seems like we do still need to ask for it specifically. Consider the following in your build.sbt:

  /* Normal scalac options */
  scalacOptions := Seq(
    "-deprecation",
    "-Ypartial-unification",
    "-Ywarn-value-discard",
    "-Ywarn-unused-import",
    "-Ywarn-dead-code",
    "-Ywarn-numeric-widen"
  )

  /* Only invoked when you do `doc` in SBT */
  scalacOptions in (Compile, doc) += "-groups"

And then your example as you have it should work.

Ovation

Answer 3

As per other answers. For maven <arg>-groups</arg>. Here is the maven version:

<plugin>
        <groupId>org.scala-tools</groupId>
        <artifactId>maven-scala-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>compile</goal>
              <goal>testCompile</goal>
            </goals>
          </execution>
            <execution>
                <id>Scaladoc</id>
                <goals>
                    <goal>doc</goal>
                </goals>
                <phase>prepare-package</phase>
                <configuration>
                    <args>
                        <arg>-no-link-warnings</arg>
                        <arg>-groups</arg>
                    </args>
                </configuration>
            </execution>
        </executions>

Tamalatamale