83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# Activiti API Doclet
|
|
|
|
This library provides a Javadoc Doclet for the generation of Activiti API documentation.
|
|
|
|
## Generating Documentation
|
|
|
|
The generated documentation is formatted in Markdown. It works great when checked into your project stored in GitHub, Bitbucket, or similar Git-based web interface.
|
|
|
|
You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR project. That plugin should be configured to use this doclet. See the snippet below.
|
|
|
|
```xml
|
|
<profile>
|
|
<id>apidocs</id>
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-javadoc-plugin</artifactId>
|
|
<version>3.8.0</version>
|
|
<executions>
|
|
<execution>
|
|
<id>generate-doclet</id>
|
|
<phase>generate-resources</phase>
|
|
<goals><goal>javadoc</goal></goals>
|
|
<configuration>
|
|
<doclet>com.inteligr8.activiti.doclet.ActivitiDoclet</doclet>
|
|
<docletArtifact>
|
|
<groupId>com.inteligr8.activiti</groupId>
|
|
<artifactId>activiti-api-doclet</artifactId>
|
|
<version>1.1-SNAPSHOT</version>
|
|
</docletArtifact>
|
|
<useStandardDocletOptions>false</useStandardDocletOptions>
|
|
<additionalOptions>
|
|
<additionalOption>--title 'API Documentation'</additionalOption>
|
|
<additionalOption>--apiName '${project.name}</additionalOption>
|
|
</additionalOptions>
|
|
<sourceFileIncludes>**/*.java</sourceFileIncludes>
|
|
<destDir>apidocs</destDir>
|
|
<reportOutputDirectory>${basedir}</reportOutputDirectory>
|
|
</configuration>
|
|
</execution>
|
|
</executions>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
</profile>
|
|
```
|
|
|
|
You can generate the docs with the following command:
|
|
|
|
```
|
|
mvn -Papidocs generate-resources
|
|
```
|
|
|
|
The documentation will be placed in `<reportOutputDirectory>/<destDir>`.
|
|
|
|
## Special Considerations
|
|
|
|
This supports many standard tags used in JavaDoc comments. This includes support for the following:
|
|
|
|
| Tag | Classes/Interfaces | Methods |
|
|
| ------------- |:------------------:|:-------:|
|
|
| `@author` | ✓ | ✓ |
|
|
| `@since` | ✓ | ✓ |
|
|
| `@version` | ✓ | ✓ |
|
|
| `@deprecated` | ✓ | ✓ |
|
|
| `@see` | ✓ | ✓ |
|
|
| `@param` | | ✓ |
|
|
| `@return` | | ✓ |
|
|
| `@throws` | | ✓ |
|
|
|
|
If the `@see` tag contains a `#` (e.g. `beanId#method`) then it will hyperlink to the specified bean and method documentation. If you use `beanId#` it will hyperlink to the bean documentation. You can use `beanId#delegate` if you want to hyperlink tot he bean and delegate method documentation.
|
|
|
|
If the `@throws` tag is a `BPMNError`, the next term is expected to be the error code, followed by the standard comment. For example, `@throws BPMNError http-404 Not found`.
|
|
|
|
The following additional non-standard tags are supported as well:
|
|
|
|
| Tag | Description |
|
|
| ------------- | ----------- |
|
|
| `@field` | A BPMN field name followed by the standard comment. This field may be used by the execution. |
|
|
| `@varIn` | An Activiti variable name followed by the standard comment. This variable may be used by the execution. |
|
|
| `@varOut` | An Activiti variable name followed by the standard comment. This variable may be set during the execution. |
|