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,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.1-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 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-SNAPSHOT</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,12 +50,14 @@
 								<version>@pom.version@</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
-							<destDir>apidocs</destDir>
+							<outputDirectory>${basedir}</outputDirectory>
-							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
 								<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/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/ActivitiDocFilter.java

@@ -28,6 +28,8 @@ 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;
@@ -102,26 +104,38 @@ class ActivitiDocFilter {
 		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()) {
+				this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
 				
-			switch (interfaceType.toString()) {
+				switch (interfaceType.toString()) {
-				case INTERFACE_JAVA_DELEGATE:
+					case INTERFACE_JAVA_DELEGATE:
-					this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
+						this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
-					delegateMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						delegateMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
+						break;
-				case INTERFACE_EXECUTION_LISTENER:
+					case INTERFACE_EXECUTION_LISTENER:
-					this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
+						this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
-					executionListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						executionListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
+						break;
-				case INTERFACE_TASK_LISTENER:
+					case INTERFACE_TASK_LISTENER:
-					this.logger.debug("The bean '{}' is a TaskListener", beanId);
+						this.logger.debug("The bean '{}' is a TaskListener", beanId);
-					taskListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						taskListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
+						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: {}", delegateMethodElements);
+		this.logger.info("delegates: {}: {}", beanId, delegateMethodElements);
 		
 		// getAllMembers() will get inherited methods
 		for (Element memberElement : this.docenv.getElementUtils().getAllMembers(classElement)) {

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/MarkdownWriter.java

@@ -68,7 +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 Pattern seeRefPattern = Pattern.compile("^([A-Za-z0-9_\\-]+)[\\.#]([A-Za-z0-9_]*)$");
 	
 	private final DocletEnvironment docenv;
 	private final File outputDirectory;
@@ -135,7 +135,7 @@ class MarkdownWriter {
 				this.buildDocumentation(commentTree, beanModel);
 				for (DocTree tag : commentTree.getBlockTags()) {
 					this.buildTagModel(tag, beandoc.getBeanId(),
-							null, null, null, beanModel);
+							null, null, null, null, null, null, beanModel);
 				}
 			}
 			
@@ -186,6 +186,9 @@ class MarkdownWriter {
 		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<>();
 		
@@ -196,11 +199,14 @@ class MarkdownWriter {
 			this.buildDocumentation(methodCommentTree, sigModel);
 			for (DocTree tag : methodCommentTree.getBlockTags()) {
 				this.buildTagModel(tag, logId,
-						paramComments, throwComments, errorComments, sigModel);
+						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);
@@ -216,12 +222,15 @@ class MarkdownWriter {
 	private void buildDocumentation(DocCommentTree commentTree, JavadocDocumentable docuable) {
 		if (commentTree.getFirstSentence() != null)
 			docuable.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
-		if (commentTree.getBody() != null)
+		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) {
@@ -246,6 +255,33 @@ class MarkdownWriter {
 					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;
@@ -295,6 +331,45 @@ class MarkdownWriter {
 		}
 	}
 	
+	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()) {

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

@@ -25,6 +25,12 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java
 	
 	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;
 	
 	private Map<String, ThrowFreemarkerModel> throwTypes = new LinkedHashMap<>();
@@ -55,6 +61,30 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java
 		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;
 	}

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,24 +1,26 @@
-
 # ${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>
+<#if tags.author??><#list tags.author as author>*Author*: ${author}</#list>
-*Author*: ${author}
+</#if><#if tags.since??>*Since Version*: ${tags.since[0]}
-</#list></#if><#if tags.since??>*Since Version*: ${tags.since[0]}
 </#if><#if tags.version??>*Version*: ${tags.version[0]}
-</#if><#if tags.deprecated??>*Deprecated*</#if>
+</#if><#if tags.deprecated??>*Deprecated*</#if></#if>
 
-</#if>
 <#if docBody??>${docBody}<#else>No documentation available.</#if>
+<#if (tags.see?? || seeRefs?size > 0)>
 
-<#if (tags.see?? || seeRefs?size > 0)><#list seeRefs as seeRef>
+<#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})
-</#list><#if tags.see??><#list tags.see as see>
+</#if></#list><#if tags.see??><#list tags.see as see>
 *See Also*: ${see}
-</#list></#if>
+</#list></#if></#if>
-
-</#if>
 <#if hasDelegate>
-## Delegate Expression Uses
+
+## <a name="delegate"></a> Delegate Expression Uses
 
 This bean may be used as a *Delegate* using the "Delegate Expression" field as shown in the snippet below.
 
@@ -26,28 +28,15 @@ This bean may be used as a *Delegate* using the "Delegate Expression" field as s
 ${r"${"}${beanId}${r"}"}
 ```
 
-<#if delegateMethod??>
+<#if delegateMethod?? || executionListenerMethod?? || taskListenerMethod??>
-You may use it in a **Service Task**.
+<#assign taskUses = [] />
-
+<#if delegateMethod??><#assign taskUses = taskUses + ["**Service Task**"] /><#assign _delegateMethod = delegateMethod /></#if>
-<#if delegateMethod.docBody??>${delegateMethod.docBody}<#else>No additional documentation available.</#if>
+<#if executionListenerMethod??><#assign taskUses = taskUses + ["**Execution Listener**"] /><#assign _delegateMethod = executionListenerMethod /></#if>
-
+<#if taskListenerMethod??><#assign taskUses = taskUses + ["**Task Listener**"] /><#assign _delegateMethod = taskListenerMethod /></#if>
----
+You may use it in a ${taskUses?join(" or ")}.
-
+<@sigdoc sig=_delegateMethod showParams=false/>
-</#if><#if executionListenerMethod??>
-You may use it in an **Execution Listener**.
-
-<#if executionListenerMethod.docBody??>${executionListenerMethod.docBody}<#else>No additional documentation available.</#if>
-
----
-
-</#if><#if taskListenerMethod??>
-You may use it in a **Task Listener**.
-
-<#if taskListenerMethod.docBody??>${taskListenerMethod.docBody}<#else>No additional documentation available.</#if>
-
----
-
 </#if></#if><#if (methods?size > 0)>
+
 ## Expression Uses
 
 This bean and its methods may be used in any "Expression" field or script in a Script Task in Activiti.
@@ -58,62 +47,81 @@ This bean and its methods may be used in any "Expression" field or script in a S
 | ${nameColumn?right_pad(32)} | <#if method.docFirstSentence??>${method.docFirstSentence?right_pad(24)}<#else>No documentation available.</#if> |
 </#list>
 
----
-
 <#list methods as method>
-## <a name="${method.methodName}"></a> `${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>
+[Back to Index](index.md)
-*Author*: ${author}
+
-</#list>
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
-</#if>
+
-<#if sig.tags.since??>*Since Version*: ${sig.tags.since[0]}</#if>
+<#macro sigdoc sig showParams>
-<#if sig.tags.version??>*Version*: ${sig.tags.version[0]}</#if>
+<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.version?? || sig.tags.deprecated??)>
-<#if sig.tags.deprecated??>*Deprecated*</#if>
+
+<#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?? || sig.seeRefs?size > 0)><#list sig.seeRefs as seeRef>
-*See Also*: [`${seeRef.beanId}.${seeRef.methodName}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
-</#list><#if sig.tags.see??><#list sig.tags.see as see>
-*See Also*: ${see}
-</#list></#if>
-
 </#if>
----
+<#if (sig.tags.see?? || sig.seeRefs?size > 0)>
 
-</#list></#list></#if>
+<#list sig.seeRefs as seeRef><#if seeRef.methodName == "">
-[Back to Index](index.md)
+*See Also*: [`${seeRef.beanId}`](bean-${seeRef.beanId}.md)
-
+<#elseif seeRef.methodName == "delegate">
-Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
+*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>
+</#if>
+</#macro>