added task listener integration test

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,16 +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.1</version>
+								<version>1.1-SNAPSHOT</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
-							<destDir>apidocs</destDir>
-							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
-								<additionalOption>--flavor bitbucket</additionalOption>
 								<additionalOption>--title 'API Documentation'</additionalOption>
 								<additionalOption>--apiName '${project.name}</additionalOption>
 							</additionalOptions>
+					        <sourceFileIncludes>**/*.java</sourceFileIncludes>
+							<destDir>apidocs</destDir>
+							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 						</configuration>
 					</execution>
 				</executions>
@@ -47,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 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. |

pom.xml

@@ -4,7 +4,7 @@
     <groupId>com.inteligr8.activiti</groupId>
     <artifactId>activiti-api-doclet</artifactId>
     <packaging>jar</packaging>
-    <version>1.0.2</version>
+    <version>1.1-SNAPSHOT</version>
     
     <name>Activiti Doclet</name>
     <description>JavaDoc Doclet for Activiti Extension APIs</description>
@@ -41,7 +41,7 @@
     	<maven.compiler.release>11</maven.compiler.release>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         
-        <spring.version>5.3.24</spring.version>
+        <spring.version>6.2.2</spring.version>
     </properties>
     
     <dependencies>
@@ -53,7 +53,7 @@
     	<dependency>
     		<groupId>org.freemarker</groupId>
     		<artifactId>freemarker</artifactId>
-    		<version>2.3.31</version>
+    		<version>2.3.34</version>
     	</dependency>
     	<dependency>
     		<groupId>org.slf4j</groupId>
@@ -63,16 +63,24 @@
     </dependencies>
     
     <build>
+		<pluginManagement>
+			<plugins>
+				<plugin>
+					<artifactId>maven-invoker-plugin</artifactId>
+					<version>3.9.0</version>
+				</plugin>
+			</plugins>
+		</pluginManagement>
     	<plugins>
 			<plugin>
 				<artifactId>maven-invoker-plugin</artifactId>
-				<version>3.2.2</version>
 				<configuration>
 					<projectsDirectory>${basedir}/src/it</projectsDirectory>
 					<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
 					<localRepositoryPath>${project.build.directory}/it-repo</localRepositoryPath>
 					<mavenHome>${env.MAVEN_HOME}</mavenHome>
 					<debug>true</debug>
+					<skipInvocation>${skipTests}</skipInvocation>
 					<properties>
 						<project.main.basedir>${basedir}</project.main.basedir>
 					</properties>
@@ -98,7 +106,7 @@
 				<dependency>
 					<groupId>org.activiti</groupId>
 					<artifactId>activiti-engine</artifactId>
-					<version>7.4.0</version>
+					<version>7.11.1</version>
 				</dependency>
     		</dependencies>
 			<repositories>
@@ -119,7 +127,6 @@
 				<plugins>
 					<plugin>
 						<artifactId>maven-invoker-plugin</artifactId>
-						<version>3.2.2</version>
 						<executions>
 							<execution>
 								<id>run-its</id>
@@ -158,7 +165,7 @@
 					</plugin>
 					<plugin>
 						<artifactId>maven-javadoc-plugin</artifactId>
-						<version>3.4.1</version>
+						<version>3.11.2</version>
 						<executions>
 							<execution>
 								<id>javadoc</id>
@@ -184,7 +191,7 @@
 					<plugin>
 						<groupId>org.sonatype.plugins</groupId>
 						<artifactId>nexus-staging-maven-plugin</artifactId>
-						<version>1.6.13</version>
+						<version>1.7.0</version>
 						<configuration>
 							<serverId>ossrh</serverId>
 							<nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>

src/it/base/pom.xml

@@ -22,12 +22,12 @@
 		<dependency>
 			<groupId>org.activiti</groupId>
 			<artifactId>activiti-engine</artifactId>
-			<version>7.4.0</version>
+			<version>7.11.1</version>
 		</dependency>
 		<dependency>
 			<groupId>org.springframework</groupId>
 			<artifactId>spring-context</artifactId>
-			<version>5.3.24</version>
+			<version>6.2.2</version>
 		</dependency>
 	</dependencies>
 	
@@ -36,7 +36,7 @@
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
-				<version>3.4.1</version>
+				<version>3.11.2</version>
 				<executions>
 					<execution>
 						<id>generate-doclet</id>
@@ -50,13 +50,14 @@
 								<version>@pom.version@</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
-							<destDir>apidocs</destDir>
+							<outputDirectory>${basedir}</outputDirectory>
-							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
-								<additionalOption>--flavor bitbucket</additionalOption>
 								<additionalOption>--title 'Example Title'</additionalOption>
 								<additionalOption>--apiName '${project.name}'</additionalOption>
 							</additionalOptions>
+
+							<!-- This is required in maven-javadoc-plugin v3.5+ -->
+							<sourceFileIncludes>**/*.java</sourceFileIncludes>
 						</configuration>
 					</execution>
 				</executions>

src/it/base/src/main/java/TestExtraTagsBean.java

@@ -0,0 +1,23 @@
+
+import org.springframework.stereotype.Component;
+
+/**
+ * This is an example comment for the class TestExtraTagsBean.
+ * 
+ * @author brian@inteligr8.com
+ * @version 1.0
+ */
+@Component("extra")
+public class TestExtraTagsBean {
+	
+	/**
+	 * This is an example comment for the method apiMethod1()
+	 * 
+	 * @field field1 An example field comment.
+	 * @varIn var1 An example input variable comment.
+	 * @varOut var2 An example output variable comment.
+	 */
+	public void apiMethod1() {
+	}
+
+}

src/it/base/src/main/java/TestNamedBean.java

@@ -35,8 +35,9 @@ public class TestNamedBean {
 	 * This is an example comment for the method apiMethod3()
 	 * 
 	 * @param param An example parameter comment.
+	 * @param classType An example generic parameter.
 	 */
-	public void apiMethod3(String param) {
+	public <T> void apiMethod3(String param, Class<T> classType) {
 	}
 	
 	/**
@@ -85,7 +86,9 @@ public class TestNamedBean {
 	 * @throws java.lang.Exception An exception comment.
 	 * @throws org.activiti.engine.delegate.BpmnError http-404
 	 * @throws BpmnError http-400 A client error.
-	 * @see `test.bean`
+	 * @see test-sub.apiMethod10
+	 * @see {@link http://inteligr8.com}
+	 * @see [Inteligr8](http://inteligr8.com)
 	 * @see http://inteligr8.com
 	 */
 	public String apiMethod8(String param) throws Exception {

src/it/base/src/main/java/TestNamedTaskListenerBean.java

@@ -0,0 +1,24 @@
+
+import org.activiti.engine.delegate.DelegateTask;
+import org.activiti.engine.delegate.TaskListener;
+import org.springframework.stereotype.Component;
+
+/**
+ * This is an example comment for the class TestNamedTaskListenerBean.
+ * 
+ * Here is a second line that happens
+ * to span multiple lines.  This class does not have an author.
+ */
+@Component("testTaskListener")
+public class TestNamedTaskListenerBean implements TaskListener {
+	
+	/**
+	 * This is an example method comment.
+	 * 
+	 * @param task A delegate task for access to the activity and process instance.
+	 */
+	@Override
+	public void notify(DelegateTask task) {
+	}
+
+}

src/main/java/com/inteligr8/activiti/doclet/ActivitiApiBeanDoc.java

@@ -31,10 +31,10 @@ class ActivitiApiBeanDoc {
 	
 	private final String beanId;
 	private TypeElement classElement;
-	private boolean isDelegate = false;
-	private boolean isExecutionListener = false;
-	private boolean isTaskListener = false;
 	private Map<String, ExecutableElement> methodElements = new HashMap<>();
+	private ExecutableElement delegateMethodElement;
+	private ExecutableElement executionListenerMethodElement;
+	private ExecutableElement taskListenerMethodElement;
 	
 	public ActivitiApiBeanDoc(String beanId, TypeElement classElement) {
 		this.beanId = beanId;
@@ -49,7 +49,31 @@ class ActivitiApiBeanDoc {
 		return classElement;
 	}
 	
-	public ActivitiApiBeanDoc addMethod(ExecutableElement method) {
+	public ExecutableElement getDelegateMethodElement() {
+		return delegateMethodElement;
+	}
+	
+	public void setDelegateMethodElement(ExecutableElement delegateMethodElement) {
+		this.delegateMethodElement = delegateMethodElement;
+	}
+	
+	public ExecutableElement getExecutionListenerMethodElement() {
+		return executionListenerMethodElement;
+	}
+	
+	public void setExecutionListenerMethodElement(ExecutableElement executionListenerMethodElement) {
+		this.executionListenerMethodElement = executionListenerMethodElement;
+	}
+	
+	public ExecutableElement getTaskListenerMethodElement() {
+		return taskListenerMethodElement;
+	}
+	
+	public void setTaskListenerMethodElement(ExecutableElement taskListenerMethodElement) {
+		this.taskListenerMethodElement = taskListenerMethodElement;
+	}
+	
+	public ActivitiApiBeanDoc addMethodElement(ExecutableElement method) {
 		this.methodElements.put(method.toString(), method);
 		return this;
 	}
@@ -71,30 +95,6 @@ class ActivitiApiBeanDoc {
 		return methodElements;
 	}
 	
-	public boolean isDelegate() {
-		return isDelegate;
-	}
-	
-	public void setDelegate(boolean isDelegate) {
-		this.isDelegate = isDelegate;
-	}
-	
-	public boolean isExecutionListener() {
-		return isExecutionListener;
-	}
-	
-	public void setExecutionListener(boolean isExecutionListener) {
-		this.isExecutionListener = isExecutionListener;
-	}
-	
-	public boolean isTaskListener() {
-		return isTaskListener;
-	}
-	
-	public void setTaskListener(boolean isTaskListener) {
-		this.isTaskListener = isTaskListener;
-	}
-	
 	@Override
 	public String toString() {
 		return this.beanId;

src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java

@@ -14,16 +14,22 @@
  */
 package com.inteligr8.activiti.doclet;
 
+import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.Comparator;
+import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Set;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.Modifier;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.type.DeclaredType;
+import javax.lang.model.type.TypeKind;
 import javax.lang.model.type.TypeMirror;
 
 import org.slf4j.Logger;
@@ -37,6 +43,10 @@ import jdk.javadoc.doclet.DocletEnvironment;
  */
 class ActivitiDocFilter {
 	
+	private final static String INTERFACE_JAVA_DELEGATE = "org.activiti.engine.delegate.JavaDelegate";
+	private final static String INTERFACE_EXECUTION_LISTENER = "org.activiti.engine.delegate.ExecutionListener";
+	private final static String INTERFACE_TASK_LISTENER = "org.activiti.engine.delegate.TaskListener";
+	
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
 	private final List<ActivitiApiBeanDoc> beandocs = new LinkedList<>();
 	private final DocletEnvironment docenv;
@@ -88,27 +98,45 @@ class ActivitiDocFilter {
 		this.logger.debug("Adding named bean: {} => {}", beanId, classElement);
 		
 		ActivitiApiBeanDoc beandoc = new ActivitiApiBeanDoc(beanId, classElement);
+		
+		Set<String> delegateMethodElements = new HashSet<>(5);
+		Set<String> executionListenerMethodElements = new HashSet<>(5);
+		Set<String> taskListenerMethodElements = new HashSet<>(5);
 
 		// getAllTypeElements() will get inherited interfaces
-		for (TypeMirror interfaceType : classElement.getInterfaces()) {
+		TypeElement superclassElement = classElement;
-			this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
+		while (superclassElement != null) {
-			
+			for (TypeMirror interfaceType : superclassElement.getInterfaces()) {
-			switch (interfaceType.toString()) {
+				this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
-				case "org.activiti.engine.delegate.JavaDelegate":
+				
-					this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
+				switch (interfaceType.toString()) {
-					beandoc.setDelegate(true);
+					case INTERFACE_JAVA_DELEGATE:
-					break;
+						this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
-				case "org.activiti.engine.delegate.ExecutionListener":
+						delegateMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
+						break;
-					beandoc.setExecutionListener(true);
+					case INTERFACE_EXECUTION_LISTENER:
-					break;
+						this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
-				case "org.activiti.engine.delegate.TaskListener":
+						executionListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					this.logger.debug("The bean '{}' is a TaskListener", beanId);
+						break;
-					beandoc.setTaskListener(true);
+					case INTERFACE_TASK_LISTENER:
-					break;
+						this.logger.debug("The bean '{}' is a TaskListener", beanId);
+						taskListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						break;
+				}
+			}
+
+			TypeMirror superclassMirror = superclassElement.getSuperclass();
+			if (superclassMirror == null) {
+				superclassElement = null;
+			} else if (superclassMirror.getKind() != TypeKind.DECLARED) {
+				superclassElement = null;
+			} else {
+				superclassElement = (TypeElement) ((DeclaredType) superclassMirror).asElement();
 			}
 		}
 		
+		this.logger.info("delegates: {}: {}", beanId, delegateMethodElements);
+		
 		// getAllMembers() will get inherited methods
 		for (Element memberElement : this.docenv.getElementUtils().getAllMembers(classElement)) {
 			switch (memberElement.getKind()) {
@@ -116,22 +144,33 @@ class ActivitiDocFilter {
 					ExecutableElement methodElement = (ExecutableElement)memberElement;
 					
 					if (!methodElement.getModifiers().contains(Modifier.PUBLIC)) {
-						this.logger.trace("Skipping non-public method: {}#{}", classElement, methodElement.getSimpleName());
+						this.logger.trace("Skipping non-public method: {}.{}", classElement, methodElement.getSimpleName());
 						continue;
 					}
 					
 					if (methodElement.getModifiers().contains(Modifier.ABSTRACT)) {
-						this.logger.trace("Skipping abstract method: {}#{}", classElement, methodElement.getSimpleName());
+						this.logger.trace("Skipping abstract method: {}.{}", classElement, methodElement.getSimpleName());
 						continue;
 					}
 					
 					if (this.skipObjectMethods && methodElement.getEnclosingElement().toString().equals("java.lang.Object")) {
-						this.logger.trace("Skipping java.lang.Object methods: {}#{}", classElement, methodElement.getSimpleName());
+						this.logger.trace("Skipping java.lang.Object method: {}.{}", classElement, methodElement.getSimpleName());
 						continue;
 					}
-
+					
-					this.logger.debug("The bean '{}' has method '{}'", beanId, methodElement);
+					if (delegateMethodElements.contains(methodElement.toString())) {
-					beandoc.addMethod(methodElement);
+						this.logger.debug("The bean '{}' has delegate method '{}'", beanId, methodElement);
+						beandoc.setDelegateMethodElement(methodElement);
+					} else if (executionListenerMethodElements.contains(methodElement.toString())) {
+						this.logger.debug("The bean '{}' has execution listener method '{}'", beanId, methodElement);
+						beandoc.setExecutionListenerMethodElement(methodElement);
+					} else if (taskListenerMethodElements.contains(methodElement.toString())) {
+						this.logger.debug("The bean '{}' has task listener method '{}'", beanId, methodElement);
+						beandoc.setTaskListenerMethodElement(methodElement);
+					} else {
+						this.logger.debug("The bean '{}' has method '{}'", beanId, methodElement);
+						beandoc.addMethodElement(methodElement);
+					}
 					break;
 				default:
 			}
@@ -153,5 +192,15 @@ class ActivitiDocFilter {
 		
 		return beandocs;
 	}
+	
+	public List<String> toStrings(Collection<? extends Element> elements) {
+		if (elements == null)
+			return Collections.emptyList();
+		
+		List<String> strs = new ArrayList<String>(elements.size());
+		for (Element element : elements)
+			strs.add(element.toString());
+		return strs;
+	}
 
 }

src/main/java/com/inteligr8/activiti/doclet/ActivitiDoclet.java

@@ -45,7 +45,6 @@ public class ActivitiDoclet implements Doclet {
 	
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
 	
-	private String flavor;
 	private String title;
 	private String apiName;
 	
@@ -57,17 +56,6 @@ public class ActivitiDoclet implements Doclet {
 	@Override
 	public Set<? extends Option> getSupportedOptions() {
 		return new HashSet<>(Arrays.asList(
-			new ValueOption("--flavor", "Flavor of the markdown host: github or bitbucket", Kind.STANDARD) {
-				@Override
-				public boolean process(String name, List<String> valueAndClasses) {
-					flavor = valueAndClasses.get(0);
-					return true;
-				}
-				
-				public String getParameters() {
-					return "'github' or 'bitbucket'";
-				}
-			},
 			new ValueOption("--title", "Title for documentation", Kind.STANDARD) {
 				@Override
 				public boolean process(String name, List<String> valueAndClasses) {
@@ -120,8 +108,6 @@ public class ActivitiDoclet implements Doclet {
 				mdwriter.setTitle(this.title);
 			if (this.apiName != null)
 				mdwriter.setApiName(this.apiName);
-			if (this.flavor != null)
-				mdwriter.setFlavor(this.flavor);
 			mdwriter.write(beandocs);
 			return true;
 		} catch (TemplateException te) {

src/main/java/com/inteligr8/activiti/doclet/BeanFreemarkerModel.java

@@ -14,17 +14,15 @@
  */
 package com.inteligr8.activiti.doclet;
 
-import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
 
 /**
  * @author brian@inteligr8.com
  */
-public class BeanFreemarkerModel {
+public class BeanFreemarkerModel implements JavadocDocumentable, JavadocTaggable {
 	
 	private String title;
 	
@@ -32,15 +30,19 @@ public class BeanFreemarkerModel {
 	
 	private String beanId;
 	
-	private String bookmark;
-	
 	private String docFirstSentence;
 
 	private String docBody;
 	
-	private Set<String> delegateRoles = new HashSet<>();
+	private MethodSignatureFreemarkerModel delegateMethod;
+
+	private MethodSignatureFreemarkerModel executionListenerMethod;
+
+	private MethodSignatureFreemarkerModel taskListenerMethod;
 
 	private Map<String, List<String>> tags = new LinkedHashMap<>();
+
+	private List<ReferenceFreemarkerModel> seeRefs = new LinkedList<>();
 	
 	private List<MethodFreemarkerModel> methods = new LinkedList<>();
 
@@ -68,14 +70,6 @@ public class BeanFreemarkerModel {
 		this.beanId = beanId;
 	}
 
-	public String getBookmark() {
-		return bookmark;
-	}
-
-	public void setBookmark(String bookmark) {
-		this.bookmark = bookmark;
-	}
-
 	public String getDocFirstSentence() {
 		return docFirstSentence;
 	}
@@ -91,13 +85,33 @@ public class BeanFreemarkerModel {
 	public void setDocBody(String docBody) {
 		this.docBody = docBody;
 	}
-
+	
-	public Set<String> getDelegateRoles() {
+	public boolean isHasDelegate() {
-		return delegateRoles;
+		return this.delegateMethod != null || this.executionListenerMethod != null || this.taskListenerMethod != null;
 	}
-
+	
-	public void setDelegateRoles(Set<String> delegateRoles) {
+	public MethodSignatureFreemarkerModel getDelegateMethod() {
-		this.delegateRoles = delegateRoles;
+		return delegateMethod;
+	}
+	
+	public void setDelegateMethod(MethodSignatureFreemarkerModel delegateMethod) {
+		this.delegateMethod = delegateMethod;
+	}
+	
+	public MethodSignatureFreemarkerModel getExecutionListenerMethod() {
+		return executionListenerMethod;
+	}
+	
+	public void setExecutionListenerMethod(MethodSignatureFreemarkerModel executionListenerMethod) {
+		this.executionListenerMethod = executionListenerMethod;
+	}
+	
+	public MethodSignatureFreemarkerModel getTaskListenerMethod() {
+		return taskListenerMethod;
+	}
+	
+	public void setTaskListenerMethod(MethodSignatureFreemarkerModel taskListenerMethod) {
+		this.taskListenerMethod = taskListenerMethod;
 	}
 
 	public Map<String, List<String>> getTags() {
@@ -107,6 +121,15 @@ public class BeanFreemarkerModel {
 	public void setTags(Map<String, List<String>> tags) {
 		this.tags = tags;
 	}
+	
+	@Override
+	public List<ReferenceFreemarkerModel> getSeeRefs() {
+		return seeRefs;
+	}
+	
+	public void setSeeRefs(List<ReferenceFreemarkerModel> seeRefs) {
+		this.seeRefs = seeRefs;
+	}
 
 	public List<MethodFreemarkerModel> getMethods() {
 		return methods;

src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java

@@ -0,0 +1,42 @@
+/*
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ * 
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.inteligr8.activiti.doclet;
+
+/**
+ * @author brian@inteligr8.com
+ */
+public class FieldFreemarkerModel {
+	
+	private String name;
+	
+	private String comment;
+	
+	public String getName() {
+		return name;
+	}
+	
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	public String getComment() {
+		return comment;
+	}
+
+	public void setComment(String comment) {
+		this.comment = comment;
+	}
+
+}

src/main/java/com/inteligr8/activiti/doclet/IndexFreemarkerModel.java

@@ -27,6 +27,10 @@ public class IndexFreemarkerModel {
 	private String apiName;
 	
 	private List<BeanFreemarkerModel> beans = new LinkedList<>();
+	
+	private boolean hasDelegateBeans;
+	
+	private boolean hasMethodBeans;
 
 	public String getTitle() {
 		return title;
@@ -51,5 +55,21 @@ public class IndexFreemarkerModel {
 	public void setBeans(List<BeanFreemarkerModel> beans) {
 		this.beans = beans;
 	}
+	
+	public boolean isHasDelegateBeans() {
+		return hasDelegateBeans;
+	}
+	
+	public void setHasDelegateBeans(boolean hasDelegateBeans) {
+		this.hasDelegateBeans = hasDelegateBeans;
+	}
+	
+	public boolean isHasMethodBeans() {
+		return hasMethodBeans;
+	}
+	
+	public void setHasMethodBeans(boolean hasMethodBeans) {
+		this.hasMethodBeans = hasMethodBeans;
+	}
 
 }

src/main/java/com/inteligr8/activiti/doclet/JavadocDocumentable.java

@@ -0,0 +1,30 @@
+/*
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ * 
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.inteligr8.activiti.doclet;
+
+/**
+ * @author brian@inteligr8.com
+ */
+public interface JavadocDocumentable {
+
+	String getDocFirstSentence();
+	
+	void setDocFirstSentence(String docFirstSentence);
+
+	String getDocBody();
+	
+	void setDocBody(String docBody);
+
+}

src/main/java/com/inteligr8/activiti/doclet/JavadocTaggable.java

@@ -0,0 +1,29 @@
+/*
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ * 
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.inteligr8.activiti.doclet;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * @author brian@inteligr8.com
+ */
+public interface JavadocTaggable {
+
+	Map<String, List<String>> getTags();
+	
+	List<ReferenceFreemarkerModel> getSeeRefs();
+
+}

src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java

@@ -38,10 +38,8 @@ import javax.lang.model.type.TypeMirror;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.sun.source.doctree.BlockTagTree;
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
-import com.sun.source.doctree.InlineTagTree;
 import com.sun.source.util.DocTrees;
 
 import freemarker.template.Configuration;
@@ -70,6 +68,7 @@ class MarkdownWriter {
 			.with(Pattern.compile("\\{ ?(@[^}]+) \\}"), "{$1}")
 			.with(Pattern.compile("\\{@link ([^}]+)\\}"), "[$1]($1)")
 			.with(Pattern.compile("([A-Za-z0-9\\-\\._]+@[A-Za-z0-9\\-\\._]+)"), "[$1](mailto:$1)");
+	private final Pattern seeRefPattern = Pattern.compile("^([A-Za-z0-9_\\-]+)[\\.#]([A-Za-z0-9_]*)$");
 	
 	private final DocletEnvironment docenv;
 	private final File outputDirectory;
@@ -77,7 +76,6 @@ class MarkdownWriter {
 	
 	private String title = "API Documentation";
 	private String apiName;
-	private String flavor;
 	
 	public MarkdownWriter(DocletEnvironment docenv) throws IOException {
 		this.docenv = docenv;
@@ -104,10 +102,6 @@ class MarkdownWriter {
 		this.apiName = apiName;
 	}
 	
-	public void setFlavor(String flavor) {
-		this.flavor = flavor;
-	}
-	
 	public void write(List<ActivitiApiBeanDoc> beandocs) throws IOException, TemplateException {
 		IndexFreemarkerModel model = this.buildModel(beandocs);
 		
@@ -135,169 +129,46 @@ class MarkdownWriter {
 			beanModel.setTitle(this.title);
 			beanModel.setApiName(this.apiName);
 			beanModel.setBeanId(beandoc.getBeanId());
-			beanModel.setBookmark(this.formatBookmark(beanModel.getBeanId()));
-			if (beandoc.isDelegate())
-				beanModel.getDelegateRoles().add("ServiceTask");
-			if (beandoc.isExecutionListener())
-				beanModel.getDelegateRoles().add("ExecutionListener");
-			if (beandoc.isTaskListener())
-				beanModel.getDelegateRoles().add("TaskListener");
 			if (commentTree != null) {
 				this.logger.debug("Found documentation for bean: {}", beandoc.getBeanId());
 				
-				if (commentTree.getFirstSentence() != null)
+				this.buildDocumentation(commentTree, beanModel);
-					beanModel.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
-				if (commentTree.getBody() != null)
-					beanModel.setDocBody(this.sanitize(commentTree.getFullBody()));
 				for (DocTree tag : commentTree.getBlockTags()) {
-					String tagName = null;
+					this.buildTagModel(tag, beandoc.getBeanId(),
-					if (tag instanceof BlockTagTree) {
+							null, null, null, null, null, null, beanModel);
-						tagName = ((BlockTagTree)tag).getTagName();
-					} else if (tag instanceof InlineTagTree) {
-						tagName = ((InlineTagTree)tag).getTagName();
-					} else {
-						this.logger.error("A tag comment is not of an expected type: {}", tag.getClass());
-						continue;
-					}
-
-					this.logger.trace("Found tag '{}' for bean: {}", tagName, beandoc.getBeanId());
-					this.putAdd(beanModel.getTags(), tagName, tag.toString());
 				}
 			}
+			
+			if (beandoc.getDelegateMethodElement() != null) {
+				beanModel.setDelegateMethod(this.buildMethodSignatureModel(beandoc, beandoc.getDelegateMethodElement()));
+				indexModel.setHasDelegateBeans(true);
+			}
+			if (beandoc.getExecutionListenerMethodElement() != null) {
+				beanModel.setExecutionListenerMethod(this.buildMethodSignatureModel(beandoc, beandoc.getExecutionListenerMethodElement()));
+				indexModel.setHasDelegateBeans(true);
+			}
+			if (beandoc.getTaskListenerMethodElement() != null) {
+				beanModel.setTaskListenerMethod(this.buildMethodSignatureModel(beandoc, beandoc.getTaskListenerMethodElement()));
+				indexModel.setHasDelegateBeans(true);
+			}
 
 			Map<Name, MethodFreemarkerModel> methodOverloads = new LinkedHashMap<>();
 			
 			for (ExecutableElement methodElement : beandoc.getSortedMethodElements()) {
-				DocCommentTree methodCommentTree = docs.getDocCommentTree(methodElement);
+				MethodSignatureFreemarkerModel sigModel = this.buildMethodSignatureModel(beandoc, methodElement);
-
-				this.logger.debug("Building documentation method model: {}.{}", beandoc.getBeanId(), methodElement);
 				
 				MethodFreemarkerModel methodModel = methodOverloads.get(methodElement.getSimpleName());
 				if (methodModel == null) {
 					methodModel = new MethodFreemarkerModel();
 					methodModel.setMethodName(methodElement.getSimpleName().toString());
-					methodModel.setBookmark(this.formatBookmark(methodModel.getMethodName()));
 					
 					methodOverloads.put(methodElement.getSimpleName(), methodModel);
 					beanModel.getMethods().add(methodModel);
+					indexModel.setHasMethodBeans(true);
 				}
 				
-				Map<String, String> paramComments = new HashMap<>();
+				if (sigModel.getDocFirstSentence() != null && methodModel.getDocFirstSentence() == null)
-				Map<String, String> throwComments = new LinkedHashMap<>();
+					methodModel.setDocFirstSentence(sigModel.getDocFirstSentence());
-				Map<String, String> errorComments = new LinkedHashMap<>();
-				
-				MethodSignatureFreemarkerModel sigModel = new MethodSignatureFreemarkerModel();
-				if (methodCommentTree != null) {
-					this.logger.debug("Found documentation for method: {}.{}", beandoc.getBeanId(), methodElement);
-					
-					if (methodCommentTree.getFirstSentence() != null) {
-						sigModel.setDocFirstSentence(this.sanitize(methodCommentTree.getFirstSentence()));
-						if (methodModel.getDocFirstSentence() == null)
-							methodModel.setDocFirstSentence(sigModel.getDocFirstSentence());
-					}
-					if (methodCommentTree.getBody() != null)
-						sigModel.setDocBody(this.sanitize(methodCommentTree.getFullBody()));
-					for (DocTree tag : methodCommentTree.getBlockTags()) {
-						Matcher matcher = this.tagPattern.matcher(tag.toString());
-						if (!matcher.find()) {
-							this.logger.warn("A tag for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-							continue;
-						}
-						
-						String tagName = matcher.group(1);
-						String tagComment = matcher.group(2).trim();
-
-						this.logger.info("Found tag '{}' for method: {}.{}", tagName, beandoc.getBeanId(), methodElement);
-
-						switch (tagName) {
-							case "param":
-								matcher = this.namedCommentPattern.matcher(tagComment);
-								if (matcher.find())
-									paramComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
-								else this.logger.warn("A @param for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-								break;
-							case "throws":
-								matcher = this.namedCommentPattern.matcher(tagComment);
-								if (matcher.find()) {
-									if (this.bpmnErrorSet.contains(matcher.group(1).toLowerCase())) {
-										Matcher ecmatcher = this.namedCommentPattern.matcher(matcher.group(2).trim());
-										if (ecmatcher.find()) {
-											errorComments.put(ecmatcher.group(1), this.sanitize(ecmatcher.group(2).trim()));
-										} else {
-											this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-										}
-									} else {
-										throwComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
-									}
-								}
-								else this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-								break;
-							default:
-								this.putAdd(sigModel.getTags(), tagName, this.sanitize(tagComment));
-						}
-					}
-				}
-				
-				StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("(");
-				
-				for (VariableElement varElement : methodElement.getParameters()) {
-					this.logger.trace("Found parameter '{}' for method: {}.{}", varElement.getSimpleName(), beandoc.getBeanId(), methodElement);
-					
-					ParamFreemarkerModel paramModel = new ParamFreemarkerModel();
-					paramModel.setName(varElement.getSimpleName().toString());
-					paramModel.setType(varElement.asType().toString());
-					paramModel.setComment(paramComments.remove(paramModel.getName()));
-					
-					sigModel.getParams().put(paramModel.getName(), paramModel);
-					methodSignature.append(varElement.getSimpleName()).append(": ").append(varElement.asType()).append(", ");
-				}
-				
-				if (!paramComments.isEmpty())
-					this.logger.warn("The {} bean and {} method has documented parameters that don't exist; ignoring ...", beandoc.getBeanId(), methodElement);
-				
-				for (TypeMirror thrownType : methodElement.getThrownTypes()) {
-					this.logger.trace("Found thrown '{}' for method: {}.{}", thrownType, beandoc.getBeanId(), methodElement);
-					
-					if ("org.activiti.engine.delegate.BpmnError".equals(thrownType.toString()) && !errorComments.isEmpty())
-						continue;
-					
-					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
-					throwModel.setType(thrownType.toString());
-					throwModel.setComment(throwComments.remove(throwModel.getType()));
-					
-					sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
-				}
-				
-				for (Entry<String, String> throwComment : throwComments.entrySet()) {
-					this.logger.trace("Found documented but not declared thrown '{}' for method: {}.{}", throwComment.getKey(), beandoc.getBeanId(), methodElement);
-
-					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
-					throwModel.setType(throwComment.getKey());
-					throwModel.setComment(throwComment.getValue());
-					
-					sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
-				}
-				
-				for (Entry<String, String> errorComment : errorComments.entrySet()) {
-					this.logger.trace("Found BPMN error thrown code '{}' for method: {}.{}", errorComment.getKey(), beandoc.getBeanId(), methodElement);
-
-					ThrowFreemarkerModel errorModel = new ThrowFreemarkerModel();
-					errorModel.setType(errorComment.getKey());
-					errorModel.setComment(errorComment.getValue());
-					
-					sigModel.getBpmnErrors().put(errorModel.getType(), errorModel);
-				}
-
-				this.logger.trace("Found return '{}' for method: {}.{}", methodElement.getReturnType(), beandoc.getBeanId(), methodElement);
-				if (!"void".equals(methodElement.getReturnType().toString()))
-					sigModel.setReturnType(methodElement.getReturnType().toString());
-				
-				if (methodSignature.charAt(methodSignature.length()-1) != '(')
-					methodSignature.delete(methodSignature.length()-2, methodSignature.length());
-				methodSignature.append("): ").append(methodElement.getReturnType());
-				
-				this.logger.debug("Found method signature: {}", methodSignature);
-				sigModel.setMethodSignature(methodSignature.toString());
 				
 				methodModel.getSignatures().add(sigModel);
 			}
@@ -308,6 +179,256 @@ class MarkdownWriter {
 		return indexModel;
 	}
 	
+	private MethodSignatureFreemarkerModel buildMethodSignatureModel(ActivitiApiBeanDoc beandoc, ExecutableElement methodElement) {
+		String logId = beandoc.getBeanId() + "." + methodElement.toString();
+		DocCommentTree methodCommentTree = this.docenv.getDocTrees().getDocCommentTree(methodElement);
+
+		this.logger.debug("Building documentation method model: {}", logId);
+		
+		Map<String, String> paramComments = new HashMap<>();
+		Map<String, String> fieldComments = new LinkedHashMap<>();
+		Map<String, String> varInComments = new LinkedHashMap<>();
+		Map<String, String> varOutComments = new LinkedHashMap<>();
+		Map<String, String> throwComments = new LinkedHashMap<>();
+		Map<String, String> errorComments = new LinkedHashMap<>();
+		
+		MethodSignatureFreemarkerModel sigModel = new MethodSignatureFreemarkerModel();
+		if (methodCommentTree != null) {
+			this.logger.debug("Found documentation for '{}'", logId);
+
+			this.buildDocumentation(methodCommentTree, sigModel);
+			for (DocTree tag : methodCommentTree.getBlockTags()) {
+				this.buildTagModel(tag, logId,
+						paramComments, fieldComments, varInComments, varOutComments, throwComments, errorComments, sigModel);
+			}
+		}
+		
+		this.buildMethodArguments(methodElement, logId, paramComments, sigModel);
+		this.buildMethodFields(methodElement, logId, fieldComments, sigModel);
+		this.buildMethodVariablesIn(methodElement, logId, varInComments, sigModel);
+		this.buildMethodVariablesOut(methodElement, logId, varOutComments, sigModel);
+		this.buildMethodThrows(methodElement, logId, throwComments, !errorComments.isEmpty(), sigModel);
+		this.buildMethodErrors(methodElement, logId, errorComments, sigModel);
+		this.buildMethodReturns(methodElement, logId, sigModel);
+		this.buildMethodBriefSignature(methodElement, sigModel);
+		this.buildMethodSignature(methodElement, sigModel);
+
+		if (!paramComments.isEmpty())
+			this.logger.warn("'{}' has documented parameters {} that don't exist; ignoring ...", logId, paramComments.keySet());
+		
+		return sigModel;
+	}
+	
+	private void buildDocumentation(DocCommentTree commentTree, JavadocDocumentable docuable) {
+		if (commentTree.getFirstSentence() != null)
+			docuable.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
+		if (commentTree.getFullBody() != null && !commentTree.getFullBody().isEmpty())
+			docuable.setDocBody(this.sanitize(commentTree.getFullBody()));
+	}
+	
+	private void buildTagModel(DocTree tag, String logId,
+			Map<String, String> paramComments,
+			Map<String, String> fieldComments,
+			Map<String, String> varInComments,
+			Map<String, String> varOutComments,
+			Map<String, String> throwComments,
+			Map<String, String> errorComments,
+			JavadocTaggable sigModel) {
+		Matcher matcher = this.tagPattern.matcher(tag.toString());
+		if (!matcher.find()) {
+			this.logger.warn("A tag for '{}' is improperly formatted", logId);
+			return;
+		}
+		
+		String tagName = matcher.group(1);
+		String tagComment = matcher.group(2).trim();
+
+		this.logger.trace("Found tag '{}' for '{}'", tagName, logId);
+
+		switch (tagName) {
+			case "param":
+				if (paramComments == null)
+					break;
+				
+				matcher = this.namedCommentPattern.matcher(tagComment);
+				if (matcher.find())
+					paramComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+				else this.logger.warn("A @param for the {} bean and {} method is improperly formatted", logId);
+				return;
+			case "field":
+				if (fieldComments == null)
+					break;
+				
+				matcher = this.namedCommentPattern.matcher(tagComment);
+				if (matcher.find())
+					fieldComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+				else this.logger.warn("A @field for the {} bean and {} method is improperly formatted", logId);
+				return;
+			case "varIn":
+				if (varInComments == null)
+					break;
+				
+				matcher = this.namedCommentPattern.matcher(tagComment);
+				if (matcher.find())
+					varInComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+				else this.logger.warn("A @varIn for the {} bean and {} method is improperly formatted", logId);
+				return;
+			case "varOut":
+				if (varOutComments == null)
+					break;
+				
+				matcher = this.namedCommentPattern.matcher(tagComment);
+				if (matcher.find())
+					varOutComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+				else this.logger.warn("A @varOut for the {} bean and {} method is improperly formatted", logId);
+				return;
+			case "throws":
+				if (throwComments == null)
+					break;
+				
+				matcher = this.namedCommentPattern.matcher(tagComment);
+				if (matcher.find()) {
+					if (this.bpmnErrorSet.contains(matcher.group(1).toLowerCase())) {
+						Matcher ecmatcher = this.namedCommentPattern.matcher(matcher.group(2).trim());
+						if (ecmatcher.find()) {
+							errorComments.put(ecmatcher.group(1), this.sanitize(ecmatcher.group(2).trim()));
+						} else {
+							this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", logId);
+						}
+					} else {
+						throwComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+					}
+				}
+				else this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", logId);
+				return;
+			case "see":
+				matcher = this.seeRefPattern.matcher(tagComment);
+				if (matcher.find()) {
+					ReferenceFreemarkerModel model = new ReferenceFreemarkerModel();
+					model.setBeanId(matcher.group(1));
+					model.setMethodName(matcher.group(2));
+					sigModel.getSeeRefs().add(model);
+					return;
+				}
+			default:
+		}
+
+		this.putAdd(sigModel.getTags(), tagName, this.sanitize(tagComment));
+	}
+	
+	private void buildMethodArguments(ExecutableElement methodElement, String logId,
+			Map<String, String> paramComments, MethodSignatureFreemarkerModel sigModel) {
+		for (VariableElement varElement : methodElement.getParameters()) {
+			this.logger.trace("Found parameter '{}' for '{}'", varElement.getSimpleName(), logId);
+			
+			ParamFreemarkerModel paramModel = new ParamFreemarkerModel();
+			paramModel.setName(varElement.getSimpleName().toString());
+			paramModel.setType(varElement.asType().toString());
+			if (paramComments != null)
+				paramModel.setComment(paramComments.remove(paramModel.getName()));
+
+			sigModel.getParams().put(paramModel.getName(), paramModel);
+		}
+	}
+	
+	private void buildMethodFields(ExecutableElement methodElement, String logId,
+			Map<String, String> fieldComments, MethodSignatureFreemarkerModel sigModel) {
+		for (Entry<String, String> fieldComment : fieldComments.entrySet()) {
+			this.logger.trace("Found BPMN field '{}' for '{}'", fieldComment.getKey(), logId);
+			
+			FieldFreemarkerModel fieldModel = new FieldFreemarkerModel();
+			fieldModel.setName(fieldComment.getKey());
+			fieldModel.setComment(fieldComment.getValue());
+
+			sigModel.getBpmnFields().put(fieldModel.getName(), fieldModel);
+		}
+	}
+	
+	private void buildMethodVariablesIn(ExecutableElement methodElement, String logId,
+			Map<String, String> varComments, MethodSignatureFreemarkerModel sigModel) {
+		for (Entry<String, String> varComment : varComments.entrySet()) {
+			this.logger.trace("Found input variable '{}' for '{}'", varComment.getKey(), logId);
+			
+			VarFreemarkerModel varModel = new VarFreemarkerModel();
+			varModel.setName(varComment.getKey());
+			varModel.setComment(varComment.getValue());
+
+			sigModel.getVariablesIn().put(varModel.getName(), varModel);
+		}
+	}
+	
+	private void buildMethodVariablesOut(ExecutableElement methodElement, String logId,
+			Map<String, String> varComments, MethodSignatureFreemarkerModel sigModel) {
+		for (Entry<String, String> varComment : varComments.entrySet()) {
+			this.logger.trace("Found output variable '{}' for '{}'", varComment.getKey(), logId);
+			
+			VarFreemarkerModel varModel = new VarFreemarkerModel();
+			varModel.setName(varComment.getKey());
+			varModel.setComment(varComment.getValue());
+
+			sigModel.getVariablesOut().put(varModel.getName(), varModel);
+		}
+	}
+	
+	private void buildMethodThrows(ExecutableElement methodElement, String logId,
+			Map<String, String> throwComments, boolean hasBpmnErrorComments, MethodSignatureFreemarkerModel sigModel) {
+		for (TypeMirror thrownType : methodElement.getThrownTypes()) {
+			this.logger.trace("Found thrown '{}' for '{}'", thrownType, logId);
+			
+			if (hasBpmnErrorComments && this.bpmnErrorSet.contains(thrownType.toString().toLowerCase()))
+				continue;
+			
+			ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
+			throwModel.setType(thrownType.toString());
+			throwModel.setComment(throwComments.remove(throwModel.getType()));
+			
+			sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
+		}
+	}
+	
+	private void buildMethodErrors(ExecutableElement methodElement, String logId,
+			Map<String, String> errorComments, MethodSignatureFreemarkerModel sigModel) {
+		for (Entry<String, String> errorComment : errorComments.entrySet()) {
+			this.logger.trace("Found BPMN error thrown code '{}' for '{}'", errorComment.getKey(), logId);
+
+			ThrowFreemarkerModel errorModel = new ThrowFreemarkerModel();
+			errorModel.setType(errorComment.getKey());
+			errorModel.setComment(errorComment.getValue());
+			
+			sigModel.getBpmnErrors().put(errorModel.getType(), errorModel);
+		}
+	}
+	
+	private void buildMethodReturns(ExecutableElement methodElement, String logId, MethodSignatureFreemarkerModel sigModel) {
+		this.logger.trace("Found return '{}' for '{}'", methodElement.getReturnType(), logId);
+		if (!"void".equals(methodElement.getReturnType().toString()))
+			sigModel.setReturnType(methodElement.getReturnType().toString());
+	}
+	
+	private void buildMethodBriefSignature(ExecutableElement methodElement, MethodSignatureFreemarkerModel sigModel) {
+		StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("(");
+		for (ParamFreemarkerModel model : sigModel.getParams().values())
+			methodSignature.append(model.getName()).append(", ");
+		if (methodSignature.charAt(methodSignature.length()-1) != '(')
+			methodSignature.delete(methodSignature.length()-2, methodSignature.length());
+		methodSignature.append(")");
+		
+		this.logger.debug("Formulated method brief signature: {}", methodSignature);
+		sigModel.setMethodSignature(methodSignature.toString());
+	}
+	
+	private void buildMethodSignature(ExecutableElement methodElement, MethodSignatureFreemarkerModel sigModel) {
+		StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("(");
+		for (ParamFreemarkerModel model : sigModel.getParams().values())
+			methodSignature.append(model.getName()).append(": ").append(model.getType()).append(", ");
+		if (methodSignature.charAt(methodSignature.length()-1) != '(')
+			methodSignature.delete(methodSignature.length()-2, methodSignature.length());
+		methodSignature.append("): ").append(methodElement.getReturnType());
+		
+		this.logger.debug("Formulated method signature: {}", methodSignature);
+		sigModel.setMethodSignature(methodSignature.toString());
+	}
+	
 	private void writeIndexFile(IndexFreemarkerModel model) throws IOException, TemplateException {
 		File mdfile = new File(this.outputDirectory, "index.md");
 		PrintWriter mdwriter = new PrintWriter(mdfile, Charset.forName("utf-8"));
@@ -330,20 +451,6 @@ class MarkdownWriter {
 		}
 	}
 	
-	private String formatBookmark(String title) {
-		if (this.flavor == null || title == null)
-			return null;
-		
-		switch (this.flavor.toLowerCase()) {
-			case "github":
-				return title.toLowerCase().replaceAll(" ", "-");
-			case "bitbucket":
-				return "markdown-header-" + title.toLowerCase().replaceAll(" ", "-");
-			default:
-				return null;
-		}
-	}
-	
 	private String sanitize(List<? extends DocTree> docs) {
 		return this.sanitize(docs.toString());
 	}

src/main/java/com/inteligr8/activiti/doclet/MethodFreemarkerModel.java

@@ -24,8 +24,6 @@ public class MethodFreemarkerModel {
 	
 	private String methodName;
 	
-	private String bookmark;
-	
 	private String docFirstSentence;
 
 	private List<MethodSignatureFreemarkerModel> signatures = new LinkedList<>();
@@ -38,14 +36,6 @@ public class MethodFreemarkerModel {
 		this.methodName = methodName;
 	}
 
-	public String getBookmark() {
-		return bookmark;
-	}
-
-	public void setBookmark(String bookmark) {
-		this.bookmark = bookmark;
-	}
-
 	public String getDocFirstSentence() {
 		return docFirstSentence;
 	}

src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java

@@ -15,14 +15,21 @@
 package com.inteligr8.activiti.doclet;
 
 import java.util.LinkedHashMap;
+import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 
-public class MethodSignatureFreemarkerModel {
+public class MethodSignatureFreemarkerModel implements JavadocDocumentable, JavadocTaggable {
 	
 	private String methodSignature;
 	
 	private Map<String, ParamFreemarkerModel> params = new LinkedHashMap<>();
+
+	private Map<String, FieldFreemarkerModel> bpmnFields = new LinkedHashMap<>();
+
+	private Map<String, VarFreemarkerModel> variablesIn = new LinkedHashMap<>();
+
+	private Map<String, VarFreemarkerModel> variablesOut = new LinkedHashMap<>();
 	
 	private String returnType;
 	
@@ -36,6 +43,8 @@ public class MethodSignatureFreemarkerModel {
 
 	private Map<String, List<String>> tags = new LinkedHashMap<>();
 
+	private List<ReferenceFreemarkerModel> seeRefs = new LinkedList<>();
+
 	public String getMethodSignature() {
 		return methodSignature;
 	}
@@ -51,6 +60,30 @@ public class MethodSignatureFreemarkerModel {
 	public void setParams(Map<String, ParamFreemarkerModel> params) {
 		this.params = params;
 	}
+	
+	public Map<String, FieldFreemarkerModel> getBpmnFields() {
+		return bpmnFields;
+	}
+	
+	public void setBpmnFields(Map<String, FieldFreemarkerModel> fields) {
+		this.bpmnFields = fields;
+	}
+	
+	public Map<String, VarFreemarkerModel> getVariablesIn() {
+		return variablesIn;
+	}
+	
+	public void setVariablesIn(Map<String, VarFreemarkerModel> variablesIn) {
+		this.variablesIn = variablesIn;
+	}
+	
+	public Map<String, VarFreemarkerModel> getVariablesOut() {
+		return variablesOut;
+	}
+	
+	public void setVariablesOut(Map<String, VarFreemarkerModel> variablesOut) {
+		this.variablesOut = variablesOut;
+	}
 
 	public String getReturnType() {
 		return returnType;
@@ -99,5 +132,13 @@ public class MethodSignatureFreemarkerModel {
 	public void setTags(Map<String, List<String>> tags) {
 		this.tags = tags;
 	}
+	
+	public List<ReferenceFreemarkerModel> getSeeRefs() {
+		return seeRefs;
+	}
+	
+	public void setSeeRefs(List<ReferenceFreemarkerModel> seeRefs) {
+		this.seeRefs = seeRefs;
+	}
 
 }

src/main/java/com/inteligr8/activiti/doclet/ReferenceFreemarkerModel.java

@@ -0,0 +1,42 @@
+/*
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ * 
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.inteligr8.activiti.doclet;
+
+/**
+ * @author brian@inteligr8.com
+ */
+public class ReferenceFreemarkerModel {
+	
+	private String beanId;
+	
+	private String methodName;
+
+	public String getBeanId() {
+		return beanId;
+	}
+
+	public void setBeanId(String beanId) {
+		this.beanId = beanId;
+	}
+
+	public String getMethodName() {
+		return methodName;
+	}
+
+	public void setMethodName(String methodName) {
+		this.methodName = methodName;
+	}
+
+}

src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java

@@ -0,0 +1,42 @@
+/*
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ * 
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.inteligr8.activiti.doclet;
+
+/**
+ * @author brian@inteligr8.com
+ */
+public class VarFreemarkerModel {
+	
+	private String name;
+	
+	private String comment;
+	
+	public String getName() {
+		return name;
+	}
+	
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	public String getComment() {
+		return comment;
+	}
+
+	public void setComment(String comment) {
+		this.comment = comment;
+	}
+
+}

src/main/resources/templates/bean.md.ftl

@@ -1,96 +1,127 @@
-
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
+<#if (tags.author?? || tags.since?? || tags.version?? || tags.deprecated??)>
 
-<#if (tags.author?? || tags.since?? || tags.deprecated??)>
+<#if tags.author??><#list tags.author as author>*Author*: ${author}</#list>
-<#if tags.author??><#list tags.author as author>
+</#if><#if tags.since??>*Since Version*: ${tags.since[0]}
-*Author*: ${author}
+</#if><#if tags.version??>*Version*: ${tags.version[0]}
-</#list></#if>
+</#if><#if tags.deprecated??>*Deprecated*</#if></#if>
-<#if tags.since??>*Since*: ${tags.since[0]}</#if>
-<#if tags.deprecated??>*Deprecated*</#if>
 
-</#if>
 <#if docBody??>${docBody}<#else>No documentation available.</#if>
+<#if (tags.see?? || seeRefs?size > 0)>
 
-<#if tags.see??><#list tags.see as see>
+<#list seeRefs as seeRef><#if seeRef.methodName == "">
+*See Also*: [`${seeRef.beanId}`](bean-${seeRef.beanId}.md)
+<#elseif seeRef.methodName == "delegate">
+*See Also*: [`${seeRef.beanId}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
+<#else>
+*See Also*: [`${seeRef.beanId}.${seeRef.methodName}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
+</#if></#list><#if tags.see??><#list tags.see as see>
 *See Also*: ${see}
-</#list>
+</#list></#if></#if>
+<#if hasDelegate>
 
-</#if>
+## <a name="delegate"></a> Delegate Expression Uses
-<#if (delegateRoles?size > 0)>
-## Delegate Uses
 
-This bean may be used in the following entities and their fields in Activiti.  In these cases, the value of the "Delegate Expression" field should be as shown in the snippet below.
+This bean may be used as a *Delegate* using the "Delegate Expression" field as shown in the snippet below.
 
 ```javascript
 ${r"${"}${beanId}${r"}"}
 ```
 
-<#if delegateRoles?seq_contains("ServiceTask") >
+<#if delegateMethod?? || executionListenerMethod?? || taskListenerMethod??>
-- Any **Non-Listener Delegate Expression** (usually a Service Task)
+<#assign taskUses = [] />
-</#if><#if delegateRoles?seq_contains("ExecutionListener") >
+<#if delegateMethod??><#assign taskUses = taskUses + ["**Service Task**"] /><#assign _delegateMethod = delegateMethod /></#if>
-- Any **Execution Listener Delegate Expression**
+<#if executionListenerMethod??><#assign taskUses = taskUses + ["**Execution Listener**"] /><#assign _delegateMethod = executionListenerMethod /></#if>
-</#if><#if delegateRoles?seq_contains("TaskListener") >
+<#if taskListenerMethod??><#assign taskUses = taskUses + ["**Task Listener**"] /><#assign _delegateMethod = taskListenerMethod /></#if>
-- Any **Task Listener Delegate Expression**
+You may use it in a ${taskUses?join(" or ")}.
-</#if>
+<@sigdoc sig=_delegateMethod showParams=false/>
+</#if></#if><#if (methods?size > 0)>
 
-</#if>
+## Expression Uses
-## Expression Methods
 
 This bean and its methods may be used in any "Expression" field or script in a Script Task in Activiti.
 
-| Method Name                       | Brief Documentation      |
+| Method Name                      | Brief Documentation      |
-| --------------------------------- | ------------------------ |
+| -------------------------------- | ------------------------ |
-<#list methods as method>
+<#list methods as method><#assign nameColumn = "[`${method.methodName}`](#${method.methodName})">
-	<#assign nameColumn = "[`${method.methodName}`](#${method.bookmark})">
 | ${nameColumn?right_pad(32)} | <#if method.docFirstSentence??>${method.docFirstSentence?right_pad(24)}<#else>No documentation available.</#if> |
 </#list>
 
 <#list methods as method>
-### `${method.methodName}`
+### <a name="${method.methodName}"></a> `${method.methodName}`
 
 <#list method.signatures as sig>
 **`${beanId}.${sig.methodSignature}`**
+<@sigdoc sig=sig showParams=true/>
+</#list></#list></#if>
 
-<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.deprecated??)>
+---
-<#if sig.tags.author??><#list sig.tags.author as author>
+
-*Author*: ${author}
+[Back to Index](index.md)
-</#list></#if>
+
-<#if sig.tags.since??>*Since*: ${sig.tags.since[0]}</#if>
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
-<#if sig.tags.deprecated??>*Deprecated*</#if>
+
+<#macro sigdoc sig showParams>
+<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.version?? || sig.tags.deprecated??)>
+
+<#if sig.tags.author??><#list sig.tags.author as author>*Author*: ${author}</#list>
+</#if><#if sig.tags.since??>*Since Version*: ${sig.tags.since[0]}
+</#if><#if sig.tags.version??>*Version*: ${sig.tags.version[0]}
+</#if><#if sig.tags.deprecated??>*Deprecated*</#if></#if>
 
-</#if>
 <#if sig.docBody??>${sig.docBody}<#else>No documentation available.</#if>
+<#if ((showParams && sig.params?size > 0) || sig.bpmnFields?size > 0 || sig.variablesIn?size > 0)>
 
-<#if (sig.params?size > 0)>
+| Input Type               | Name                     | Java Type                                        | Documentation                      |
-| Parameter Name           | Java Type                                        | Documentation            |
+| ------------------------ | ------------------------ | ------------------------------------------------ | ---------------------------------- |
-| ------------------------ | ------------------------------------------------ | ------------------------ |
+<#if showParams><#list sig.params as paramName, param>
-<#list sig.params as paramName, param>
+| Method Parameter         | ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if (param.comment?? && param.comment?length > 0)>${param.comment?right_pad(32)}<#else>No documentation available.</#if> |
-| ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if (param.comment?? && param.comment?length > 0)>${param.comment?right_pad(24)}<#else>No documentation available.</#if> |
+</#list></#if>
+<#if (sig.bpmnFields?size > 0)>
+<#list sig.bpmnFields as fieldName, field>
+| BPMN Field               | ${("`" + fieldName + "`")?right_pad(24)} | ${("")?right_pad(48)} | <#if (field.comment?? && field.comment?length > 0)>${field.comment?right_pad(32)}<#else>No documentation available.</#if> |
 </#list>
-
 </#if>
-<#if (sig.returnType?? || sig.throwTypes?size > 0)>
+<#if (sig.variablesIn?size > 0)>
-| Result Type              | Java Type or BPMN Error Code                     | Documentation            |
+<#list sig.variablesIn as varName, var>
-| ------------------------ | ------------------------------------------------ | ------------------------ |
+| Activiti Variable        | ${("`" + varName + "`")?right_pad(24)} | ${("")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available.</#if> |
+</#list>
+</#if>
+</#if>
+<#if (sig.returnType?? || sig.variablesOut?size > 0 || sig.throwTypes?size > 0)>
+
+| Result Type              | Java Type, Name, or Error Code                   | Documentation                    |
+| ------------------------ | ------------------------------------------------ | -------------------------------- |
 <#if sig.returnType??>
-| Return Value             | ${("`" + sig.returnType + "`")?right_pad(48)} | <#if (sig.tags.return?? && sig.tags.return[0]?length > 0)>${sig.tags.return[0]?right_pad(24)}<#else>No documentation available.</#if> |
+| Return Value             | ${("`" + sig.returnType + "`")?right_pad(48)} | <#if (sig.tags.return?? && sig.tags.return[0]?length > 0)>${sig.tags.return[0]?right_pad(32)}<#else>No documentation available.</#if> |
+</#if>
+<#if (sig.variablesOut?size > 0)>
+<#list sig.variablesOut as varName, var>
+| Activiti Variable        | ${("`" + varName + "`")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available.</#if> |
+</#list>
 </#if>
 <#if (sig.throwTypes?size > 0)>
 <#list sig.throwTypes as throwType, throw>
-| Thrown Exception         | ${("`" + throwType + "`")?right_pad(48)} | <#if (throw.comment?? && throw.comment?length > 0)>${throw.comment?right_pad(24)}<#else>No documentation available.</#if> |
+| Thrown Exception         | ${("`" + throwType + "`")?right_pad(48)} | <#if (throw.comment?? && throw.comment?length > 0)>${throw.comment?right_pad(32)}<#else>No documentation available.</#if> |
 </#list>
 </#if>
 <#if (sig.bpmnErrors?size > 0)>
 <#list sig.bpmnErrors as errorCode, bpmnError>
-| Thrown BPMN Error        | ${("`" + errorCode + "`")?right_pad(48)} | <#if (bpmnError.comment?? && bpmnError.comment?length > 0)>${bpmnError.comment?right_pad(24)}<#else>No documentation available.</#if> |
+| Thrown BPMN Error        | ${("`" + errorCode + "`")?right_pad(48)} | <#if (bpmnError.comment?? && bpmnError.comment?length > 0)>${bpmnError.comment?right_pad(32)}<#else>No documentation available.</#if> |
 </#list>
 </#if>
-
 </#if>
-<#if sig.tags.see??><#list sig.tags.see as see>
+<#if (sig.tags.see?? || sig.seeRefs?size > 0)>
+
+<#list sig.seeRefs as seeRef><#if seeRef.methodName == "">
+*See Also*: [`${seeRef.beanId}`](bean-${seeRef.beanId}.md)
+<#elseif seeRef.methodName == "delegate">
+*See Also*: [`${seeRef.beanId}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
+<#else>
+*See Also*: [`${seeRef.beanId}.${seeRef.methodName}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
+</#if></#list><#if sig.tags.see??><#list sig.tags.see as see>
 *See Also*: ${see}
 </#list>
-
 </#if>
-</#list>
+</#if>
-</#list>
+</#macro>

src/main/resources/templates/index.md.ftl

@@ -17,11 +17,28 @@ Activiti has a set of features that allow a model designer to call these Java-ba
 
 It is important to note that Activiti expressions use the JUEL language and Activiti scripts use the specified/configured language.  Popular configured languages may be JavaScript or Groovy.  In any case, the same API notation may be used.  It is also worth noting that execution/task listeners may exist on most objects.
 
+<#if hasDelegateBeans>
+## Delegates
+
+| Delegate ID                      | Brief Documentation       |
+| -------------------------------- | ------------------------- |
+<#list beans as bean><#if bean.hasDelegate>
+	<#assign idColumn = "[`${bean.beanId}`](bean-${bean.beanId}.md)">
+| ${idColumn?right_pad(32)} | <#if bean.docFirstSentence??>${bean.docFirstSentence?right_pad(24)}<#else>No documentation available.</#if> |
+</#if></#list>
+
+</#if>
+<#if hasMethodBeans>
 ## Beans
 
 | Bean ID                          | Brief Documentation       |
 | -------------------------------- | ------------------------- |
-<#list beans as bean>
+<#list beans as bean><#if (bean.methods?size > 0)>
 	<#assign idColumn = "[`${bean.beanId}`](bean-${bean.beanId}.md)">
 | ${idColumn?right_pad(32)} | <#if bean.docFirstSentence??>${bean.docFirstSentence?right_pad(24)}<#else>No documentation available.</#if> |
-</#list>
+</#if></#list>
+
+</#if>
+---
+
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).