-
Notifications
You must be signed in to change notification settings - Fork 200
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:
- The Enunciate sourcepath needs to include the source files for the precompiled classes.
- Enunciate needs to be configured to look on the sourcepath for the sources of those precompiled classes.
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 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.18.1</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 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>
See the Enunciate Gradle Project for more information.
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.