updated README

README.md

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