inteligr8/activiti-api-doclet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated README

Browse Source
This commit is contained in:
Brian Long 2025-02-10 14:30:06 -05:00
parent 12c80ad087
commit 3693afbb4a
1 changed files with 39 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -1,6 +1,12 @@
# Activiti API Doclet
This library provides a Javadoc Doclet for the generation of Activiti API documentation. 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.
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>
@ -10,7 +16,7 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.1</version>
<version>3.8.0</version>
<executions>
<execution>
<id>generate-doclet</id>
@ -21,15 +27,16 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
<docletArtifact>
<groupId>com.inteligr8.activiti</groupId>
<artifactId>activiti-api-doclet</artifactId>
<version>1.0.4</version>
<version>1.0-SNAPSHOT</version>
</docletArtifact>
<useStandardDocletOptions>false</useStandardDocletOptions>
<destDir>apidocs</destDir>
<reportOutputDirectory>${basedir}</reportOutputDirectory>
<additionalOptions>
<additionalOption>--title 'API Documentation'</additionalOption>
<additionalOption>--apiName '${project.name}</additionalOption>
</additionalOptions>
<sourceFileIncludes>**/*.java</sourceFileIncludes>
<destDir>apidocs</destDir>
<reportOutputDirectory>${basedir}</reportOutputDirectory>
</configuration>
</execution>
</executions>
@ -46,3 +53,30 @@ 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.
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. |