# 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. |