Discovering Source Files

Discovering Source Files

In order for your JavaDoc comments to show up in the artifacts generated by Enunciate, the Java source code for your API classes needs to be available to the engine. The compiled Java bytecode doesn't contain comments.

Source files that are to be compiled in the current project will always be included and available to the Enunciate engine; no extra configuration is needed. However, extra configuration might be needed to allow Enunciate to see the source code for classes that have already been compiled. Specifically, two conditions need to be met:

1. The Enunciate sourcepath needs to include the source files for the precompiled classes.
2. Enunciate needs to be configured to look on the sourcepath for the sources of those precompiled classes.

Establishing the Sourcepath

A Java sourcepath is just like a Java classpath, but it contains a list of directories and jars that contain Java source files instead of Java class files. Each executable has its own way of providing the sourcepath.

Maven

Maven users will find that the source files of artifacts that have the same groupId as the project were Enunciate is invoked will be included by default, assuming the "sources" for that artifact are available (see Multi Module Projects). Maven users can also specify sources to be included/excluded using the sourcepath-includes and sourcepath-excludes elements of the plugin configuration:

<project>
  ...

  <build>
    <plugins>
      <plugin>
        <groupId>com.webcohesion.enunciate</groupId>
        <artifactId>enunciate-maven-plugin</artifactId>
        <version>2.17.0</version>
        <configuration>
          <sourcepath-includes>
            <sourcepath-include>
              <!-- Include all sources artifacts in groupId "com.othercompany" on the sourcepath. -->
              <groupId>com.othercompany</groupId>
            </sourcepath-include>
            <sourcepath-include>
              <!-- Include the "com.external:external" artifact on the sourcepath. -->
              <groupId>com.external</groupId>
              <artifactId>external</artifactId>
            </sourcepath-include>
          </sourcepath-includes>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>assemble</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  ...
</project>

Ant

Ant users have to build and set the sourcepath:

<path id="compile.classpath">
  <!--set up the classpath you need to compile your java source files-->
</path>

<path id="enunciate.sourcepath">
  <!--set up the sourcepath-->
</path>

<enunciate basedir="src/main/java" buildDir="${enunciate.working.dir}">
  <include name="**/*.java"/>
  <classpath refid="compile.classpath"/>
  <sourcepath refid="enunciate.sourcepath"/>
  <export artifactId="docs" destination="${docs.dir}"/>
</enunciate>

Gradle

See the Enunciate Gradle Project for more information.

Configuring Enunciate Source Files

When compiling documentation, Enunciate has to be shy about which Java source files to include in the compilation. If Enunciate included every source file found on the sourcepath, the compilation would too often fail because the sourcepath often includes files that reference classes that aren't on the classpath.

Therefore, Enunciate needs to be explicitly configured to include source files of classes that have already been compiled. This is done using the api-classes configuration element:

<enunciate ...>
  ...
  <api-classes>
    <exclude pattern="com.mycompany.hide.**"/>
    <include pattern="com.mycompany.hide.ExceptThisClass"/>
    <exclude pattern="com.mycompany.api.MyClass"/>
  </api-classes>
  ...
</enunciate>

Note that this api-classes configuration element is also used to include/exclude aspects of the generated documentation. For more information, see Excluding Including Classes.