13

I have a multi-module Maven build and I would like to generate an aggregated Scaladoc in my root module, similar to what the aggregate goal for the maven-javadoc-plugin does. My first attempt was:

<project ...>
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <artifactId>maven-site-plugin</artifactId>
                    <configuration>
                        <reportPlugins>
                            <plugin>
                                <artifactId>maven-project-info-reports-plugin</artifactId>
                            </plugin>
                            <plugin>
                                <groupId>net.alchim31.maven</groupId>
                                <artifactId>scala-maven-plugin</artifactId>
                                <reports>
                                    <report>doc</report>
                                </reports>
                                <configuration>
                                    <aggregateDirectOnly>false</aggregateDirectOnly>
                                    <sendJavaToScalac>false</sendJavaToScalac>
                                </configuration>
                            </plugin>
                            <plugin>
                                <artifactId>maven-javadoc-plugin</artifactId>
                                <reports>
                                    <report>aggregate</report>
                                </reports>
                            </plugin>
                        </reportPlugins>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

However, the aggregateDirectOnly property does not seem to have any effect. I always get the Scaladoc for the individual jar-type POMs only.

I also tried to set forceAggregate to true, but it had no effect, too.

How to do this?

Christian Schlichtherle
  • 3,125
  • 1
  • 23
  • 47

1 Answers1

6

This doesn't answer the question exactly as asked, but is a solution that may actually be preferred for mixed java/scala projects until ScalaDoc is capable of parsing JavaDoc comments. It produces a single aggregated JavaDoc that includes documentation from all of the project's Scala source files as well.

The solution is simple: configure Maven to use the GenJavaDoc Scala compiler plugin so that ScalaDocs can be converted to JavaDocs. Then, use the normal javadoc:aggregate goal to aggregate the project as normal.

Here is a sample Maven profile to do this. It configures the Scala compiler to generate the JavaDocs corresponding to the Scala sources, configures Maven to treat the genjavadoc directory created by the Scala compiler as a source directory, and then configures the javadoc plugin itself (this last may be optional if you have no special JavaDoc plugin configuration requirements).

<profile>
  <id>javadoc</id>
  <build>
    <plugins>
      <plugin>
        <groupId>net.alchim31.maven</groupId>
        <artifactId>scala-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>doc</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>compile</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <args>
            <arg>-P:genjavadoc:out=${project.build.directory}/genjavadoc</arg>
          </args>
          <compilerPlugins>
            <compilerPlugin>
              <groupId>com.typesafe.genjavadoc</groupId>
              <artifactId>genjavadoc-plugin_${scala.binary.full.version}</artifactId>
              <version>0.4</version>
            </compilerPlugin>
          </compilerPlugins>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <executions>
          <execution>
            <phase>generate-sources</phase>
            <goals>
              <goal>add-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>${project.build.directory}/genjavadoc</source>
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <configuration>
          <minmemory>64m</minmemory>
          <maxmemory>2g</maxmemory>
          <outputDirectory>${project.build.directory}</outputDirectory>
          <detectLinks>true</detectLinks>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>
Raman
  • 17,606
  • 5
  • 95
  • 112
  • should this be on the reactor pom.xml ? – David H Jul 29 '15 at 14:26
  • @DavidH It should in the POM at the level at which you want to generate the docs for that module and submodules. Don't forget to use the `-Pjavadoc` to enable the profile, or make it your default configuration by putting it in the `build` section directly instead of `profile/build`. – Raman Jul 29 '15 at 15:30
  • i am familiar with maven. but i dont understand how to organize the build. lets say you have 3 modules A,B,C Dependency is like that A<-B<-C project D is the reactor for A,B,C (A,B,C are modules at D) should i create module E for generating scaladoc ? where should i put the scaladoc generation ? should it be at C module? – David H Jul 29 '15 at 17:27
  • This only generates the JavaDoc which isn't very useful for Scala code (it shows all the compiler generated classes as well.) Is there a way to generate and aggregate proper ScalaDocs with Maven? – Alessandro Vermeulen Oct 14 '15 at 15:07
  • @DavidH Put it in module D. – Raman Oct 15 '15 at 15:57
  • @AlessandroVermeulen Not as far as I know. As mentioned in the answer, ScalaDoc really needs to learn how to parse and document JavaDoc. – Raman Oct 15 '15 at 15:58
  • @Raman In our instance it already shows classes defined in Java together with their JavaDoc. What I need is to be able to aggregate all the scaladocs in my seperate modules into a single scaladoc. – Alessandro Vermeulen Oct 15 '15 at 16:03
  • @AlessandroVermeulen Ok, it needs to learn how to do that too :-) Last time I looked at this (which was admittedly over a year ago) I couldn't figure out a way. – Raman Oct 15 '15 at 16:04
  • so, do we have any final thought of how to do that ? – David H Oct 20 '15 at 16:50
  • Unfortunately, scaladoc-specific stuff such as `@tparam` makes this approach fail. – Shannon Oct 05 '16 at 22:17
  • Somehow my generated code from this is conflicting with actual source code: `[ERROR] /home/brandon/workspace/ced2ar-core-services/services-core/target/genjavadoc/edu/cornell/ncrn/ced2ar/service/ApiInfoService.java:8: error: Companions 'class ApiInfoService' and 'object ApiInfoService' must be defined in same file: [INFO] Found in /home/brandon/workspace/ced2ar-core-services/services-core/src/main/java/edu/cornell/ncrn/ced2ar/service/ApiInfoService.scala and /home/brandon/workspace/ced2ar-core-services/services-core/target/genjavadoc/edu/cornell/ncrn/ced2ar/service/ApiInfoService.java` – bbarker Sep 11 '18 at 13:23