From 7116962f9fce8ad9080e9af5d062d32e5c8a8e7f Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 10:54:49 -0500
Subject: [PATCH 01/13] upgraded plugins/dependencies

---
 pom.xml | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/pom.xml b/pom.xml
index dd1c46b..796ef3f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -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,10 +63,17 @@
     </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>
@@ -98,7 +105,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 +126,6 @@
 				<plugins>
 					<plugin>
 						<artifactId>maven-invoker-plugin</artifactId>
-						<version>3.2.2</version>
 						<executions>
 							<execution>
 								<id>run-its</id>
@@ -158,7 +164,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 +190,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>

From 0886a273e41f979a166445d5a44938a3304c1dc9 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 11:10:15 -0500
Subject: [PATCH 02/13] added @field @varIn @varOut

---
 .../activiti/doclet/FieldFreemarkerModel.java | 42 ++++++++++
 .../activiti/doclet/MarkdownWriter.java       | 79 ++++++++++++++++++-
 .../MethodSignatureFreemarkerModel.java       | 30 +++++++
 .../activiti/doclet/VarFreemarkerModel.java   | 42 ++++++++++
 src/main/resources/templates/bean.md.ftl      | 31 ++++++--
 5 files changed, 214 insertions(+), 10 deletions(-)
 create mode 100644 src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java
 create mode 100644 src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java

diff --git a/src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java
new file mode 100644
index 0000000..442778e
--- /dev/null
+++ b/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;
+	}
+
+}
diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
index 3a83c59..8c470bc 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
+++ b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
@@ -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);
@@ -222,6 +228,9 @@ class MarkdownWriter {
 	
 	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 @field 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 @field 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.getVariablesIn().put(varModel.getName(), varModel);
+		}
+	}
+	
 	private void buildMethodThrows(ExecutableElement methodElement, String logId,
 			Map<String, String> throwComments, boolean hasBpmnErrorComments, MethodSignatureFreemarkerModel sigModel) {
 		for (TypeMirror thrownType : methodElement.getThrownTypes()) {
diff --git a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java
index df6e454..3c7cdf8 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java
+++ b/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java
@@ -24,6 +24,12 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java
 	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;
 	
@@ -54,6 +60,30 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java
 	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;
diff --git a/src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java
new file mode 100644
index 0000000..5195b15
--- /dev/null
+++ b/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;
+	}
+
+}
diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl
index ee32076..d247e02 100644
--- a/src/main/resources/templates/bean.md.ftl
+++ b/src/main/resources/templates/bean.md.ftl
@@ -80,27 +80,42 @@ This bean and its methods may be used in any "Expression" field or script in a S
 <#if sig.docBody??>${sig.docBody}<#else>No documentation available.</#if>
 
 <#if (sig.params?size > 0)>
-| Parameter Name           | Java Type                                        | Documentation            |
-| ------------------------ | ------------------------------------------------ | ------------------------ |
+| Input Type               | Name                     | Java Type                                        | Documentation                      |
+| ------------------------ | ------------------------ | ------------------------------------------------ | ---------------------------------- |
 <#list sig.params as paramName, param>
-| ${("`" + 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> |
+| 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> |
 </#list>
+<#if (sig.bpmnFields?size > 0)>
+<#list sig.bpmnFields as fieldName, field>
+| BPMN Field               | ${("`" + fieldName + "`")?right_pad(48)} | ${("")?right_pad(48)} | <#if (field.comment?? && field.comment?length > 0)>${field.comment?right_pad(32)}<#else>No documentation available.</#if> |
+</#list>
+</#if>
+<#if (sig.variablesIn?size > 0)>
+<#list sig.variablesIn as varName, var>
+| Variable                 | ${("`" + varName + "`")?right_pad(48)} | ${("")?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.throwTypes?size > 0)>
-| Result Type              | Java Type or BPMN Error Code                     | Documentation            |
-| ------------------------ | ------------------------------------------------ | ------------------------ |
+| 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>
+| 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>
 

From ed4326589b79b89aa6aaa4c33a36467278899cd2 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 11:46:19 -0500
Subject: [PATCH 03/13] inherited interface recognition

---
 .../activiti/doclet/ActivitiDocFilter.java    | 46 ++++++++++++-------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java b/src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java
index 3d35afc..310096e 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java
+++ b/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,22 +104,34 @@ class ActivitiDocFilter {
 		Set<String> taskListenerMethodElements = new HashSet<>(5);
 
 		// getAllTypeElements() will get inherited interfaces
-		for (TypeMirror interfaceType : classElement.getInterfaces()) {
-			this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
-			
-			switch (interfaceType.toString()) {
-				case INTERFACE_JAVA_DELEGATE:
-					this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
-					delegateMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
-				case INTERFACE_EXECUTION_LISTENER:
-					this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
-					executionListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
-				case INTERFACE_TASK_LISTENER:
-					this.logger.debug("The bean '{}' is a TaskListener", beanId);
-					taskListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
-					break;
+		TypeElement superclassElement = classElement;
+		while (superclassElement != null) {
+			for (TypeMirror interfaceType : superclassElement.getInterfaces()) {
+				this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
+				
+				switch (interfaceType.toString()) {
+					case INTERFACE_JAVA_DELEGATE:
+						this.logger.debug("The bean '{}' is a JavaDelegate", beanId);
+						delegateMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						break;
+					case INTERFACE_EXECUTION_LISTENER:
+						this.logger.debug("The bean '{}' is a ExecutionListener", beanId);
+						executionListenerMethodElements.addAll(this.toStrings(this.docenv.getTypeUtils().asElement(interfaceType).getEnclosedElements()));
+						break;
+					case INTERFACE_TASK_LISTENER:
+						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();
 			}
 		}
 		

From 0bc4e4922b69fd461f0960276f36ab46919bc52a Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 11:46:35 -0500
Subject: [PATCH 04/13] doc formatting change with fields/variables

---
 src/main/resources/templates/bean.md.ftl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl
index d247e02..8565c62 100644
--- a/src/main/resources/templates/bean.md.ftl
+++ b/src/main/resources/templates/bean.md.ftl
@@ -87,12 +87,12 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#list>
 <#if (sig.bpmnFields?size > 0)>
 <#list sig.bpmnFields as fieldName, field>
-| BPMN Field               | ${("`" + fieldName + "`")?right_pad(48)} | ${("")?right_pad(48)} | <#if (field.comment?? && field.comment?length > 0)>${field.comment?right_pad(32)}<#else>No documentation available.</#if> |
+| 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.variablesIn?size > 0)>
 <#list sig.variablesIn as varName, var>
-| Variable                 | ${("`" + varName + "`")?right_pad(48)} | ${("")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available.</#if> |
+| APS 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>
 
@@ -105,7 +105,7 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 <#if (sig.variablesOut?size > 0)>
 <#list sig.variablesOut as varName, var>
-| Variable                 | ${("`" + varName + "`")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available.</#if> |
+| APS 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)>

From 5dcef42c91bb47239c2945908e8b87be9ab92021 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 11:47:02 -0500
Subject: [PATCH 05/13] added integration tests for fields/variables

---
 src/it/base/pom.xml                           |  9 +++++---
 .../base/src/main/java/TestExtraTagsBean.java | 23 +++++++++++++++++++
 2 files changed, 29 insertions(+), 3 deletions(-)
 create mode 100644 src/it/base/src/main/java/TestExtraTagsBean.java

diff --git a/src/it/base/pom.xml b/src/it/base/pom.xml
index 66b0cdb..c64c2aa 100644
--- a/src/it/base/pom.xml
+++ b/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>
@@ -56,6 +56,9 @@
 								<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>
diff --git a/src/it/base/src/main/java/TestExtraTagsBean.java b/src/it/base/src/main/java/TestExtraTagsBean.java
new file mode 100644
index 0000000..df3a510
--- /dev/null
+++ b/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() {
+	}
+
+}

From 1fe2bdf92c7fc760659be6ad9804eb66ed98f827 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:28:56 -0500
Subject: [PATCH 06/13] allow skippable tests

---
 pom.xml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pom.xml b/pom.xml
index 796ef3f..4d7baeb 100644
--- a/pom.xml
+++ b/pom.xml
@@ -80,6 +80,7 @@
 					<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>

From 12c80ad0871ca9e0a9b2195e4958bf85f14c1dcd Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:29:51 -0500
Subject: [PATCH 07/13] better delegate docs; minor formatting tweaks

---
 src/main/resources/templates/bean.md.ftl | 57 ++++++++++--------------
 1 file changed, 23 insertions(+), 34 deletions(-)

diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl
index 8565c62..b27f976 100644
--- a/src/main/resources/templates/bean.md.ftl
+++ b/src/main/resources/templates/bean.md.ftl
@@ -1,12 +1,10 @@
-
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
 
-<#if (tags.author?? || tags.since?? || tags.deprecated??)><#if tags.author??><#list tags.author as author>
+<#if (tags.author?? || tags.since?? || tags.version?? || tags.deprecated??)><#if tags.author??><#list tags.author as author>
 *Author*: ${author}
 </#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 docBody??>${docBody}<#else>No documentation available.</#if>
 
@@ -26,27 +24,14 @@ This bean may be used as a *Delegate* using the "Delegate Expression" field as s
 ${r"${"}${beanId}${r"}"}
 ```
 
-<#if delegateMethod??>
-You may use it in a **Service Task**.
-
-<#if delegateMethod.docBody??>${delegateMethod.docBody}<#else>No additional documentation available.</#if>
-
----
-
-</#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 delegateMethod?? || executionListenerMethod?? || taskListenerMethod??>
+<#assign taskUses = [] />
+<#if delegateMethod??><#assign taskUses = taskUses + ["**Service Task**"] /></#if>
+<#if executionListenerMethod??><#assign taskUses = taskUses + ["**Execution Listener**"] /></#if>
+<#if taskListenerMethod??><#assign taskUses = taskUses + ["**Task Listener**"] /></#if>
+You may use it in a ${taskUses?join(" or ")}.
 
+<@sigdoc sig=delegateMethod showParams=false/>
 </#if></#if><#if (methods?size > 0)>
 ## Expression Uses
 
@@ -66,7 +51,14 @@ This bean and its methods may be used in any "Expression" field or script in a S
 <#list method.signatures as sig>
 **`${beanId}.${sig.methodSignature}`**
 
-<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.deprecated??)>
+<@sigdoc sig=sig showParams=true/>
+</#list></#list></#if>
+[Back to Index](index.md)
+
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
+
+<#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}
@@ -79,12 +71,12 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 <#if sig.docBody??>${sig.docBody}<#else>No documentation available.</#if>
 
-<#if (sig.params?size > 0)>
+<#if ((showParams && sig.params?size > 0) || sig.bpmnFields?size > 0 || sig.variablesIn?size > 0)>
 | Input Type               | Name                     | Java Type                                        | Documentation                      |
 | ------------------------ | ------------------------ | ------------------------------------------------ | ---------------------------------- |
-<#list sig.params as paramName, param>
+<#if showParams><#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> |
-</#list>
+</#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> |
@@ -92,12 +84,12 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 <#if (sig.variablesIn?size > 0)>
 <#list sig.variablesIn as varName, var>
-| APS 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> |
+| 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.throwTypes?size > 0)>
+<#if (sig.returnType?? || sig.variablesOut?size > 0 || sig.throwTypes?size > 0)>
 | Result Type              | Java Type, Name, or Error Code                   | Documentation                    |
 | ------------------------ | ------------------------------------------------ | -------------------------------- |
 <#if sig.returnType??>
@@ -105,7 +97,7 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 <#if (sig.variablesOut?size > 0)>
 <#list sig.variablesOut as varName, var>
-| APS Variable             | ${("`" + varName + "`")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available.</#if> |
+| 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)>
@@ -128,7 +120,4 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 ---
 
-</#list></#list></#if>
-[Back to Index](index.md)
-
-Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
+</#macro>
\ No newline at end of file

From 3693afbb4aa9334bc74ded721dacce75622c2c5d Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:30:06 -0500
Subject: [PATCH 08/13] updated README

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 88ae2c8..1390cdd 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,12 @@
 # Activiti API Doclet
 
-This library provides a Javadoc Doclet for the generation of Activiti API documentation.  You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR project.  That plugin should be configured to use this doclet.  See the snippet below.
+This library provides a Javadoc Doclet for the generation of Activiti API documentation.
+
+## Generating Documentation
+
+The generated documentation is formatted in Markdown.  It works great when checked into your project stored in GitHub, Bitbucket, or similar Git-based web interface.
+
+You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR project.  That plugin should be configured to use this doclet.  See the snippet below.
 
 ```xml
 <profile>
@@ -10,7 +16,7 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
-				<version>3.4.1</version>
+				<version>3.8.0</version>
 				<executions>
 					<execution>
 						<id>generate-doclet</id>
@@ -21,15 +27,16 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
 							<docletArtifact>
 								<groupId>com.inteligr8.activiti</groupId>
 								<artifactId>activiti-api-doclet</artifactId>
-								<version>1.0.4</version>
+								<version>1.0-SNAPSHOT</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
-							<destDir>apidocs</destDir>
-							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
 								<additionalOption>--title 'API Documentation'</additionalOption>
 								<additionalOption>--apiName '${project.name}</additionalOption>
 							</additionalOptions>
+					        <sourceFileIncludes>**/*.java</sourceFileIncludes>
+							<destDir>apidocs</destDir>
+							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 						</configuration>
 					</execution>
 				</executions>
@@ -46,3 +53,30 @@ mvn -Papidocs generate-resources
 ```
 
 The documentation will be placed in `<reportOutputDirectory>/<destDir>`.
+
+## Special Considerations
+
+This supports many standard tags used in JavaDoc comments.  This includes support for the following:
+
+| Tag           | Classes/Interfaces | Methods |
+| ------------- |:------------------:|:-------:|
+| `@author`     | ✓                  | ✓       |
+| `@since`      | ✓                  | ✓       |
+| `@version`    | ✓                  | ✓       |
+| `@deprecated` | ✓                  | ✓       |
+| `@see`        | ✓                  | ✓       |
+| `@param`      |                    | ✓       |
+| `@return`     |                    | ✓       |
+| `@throws`     |                    | ✓       |
+
+If the `@see` tag contains a `#` (e.g. `beanId#method`) then it will hyperlink to the specified bean and method.
+
+If the `@throws` tag is a `BPMNError`, the next term is expected to be the error code, followed by the standard comment.  For example, `@throws BPMNError http-404 Not found`.
+
+The following additional non-standard tags are supported as well:
+
+| Tag           | Description |
+| ------------- | ----------- |
+| `@field`      | A BPMN field name followed by the standard comment.  This field may be used by the execution. |
+| `@varIn`      | An Activiti variable name followed by the standard comment.  This variable may be used by the execution. |
+| `@varOut`     | An Activiti variable name followed by the standard comment.  This variable may be set during the execution. |

From 39709ca5896ff2b35e9e4e6fb88ba31724ccac60 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:33:22 -0500
Subject: [PATCH 09/13] v1.1.x pom and README

---
 README.md | 2 +-
 pom.xml   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1390cdd..48f5e9d 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR
 							<docletArtifact>
 								<groupId>com.inteligr8.activiti</groupId>
 								<artifactId>activiti-api-doclet</artifactId>
-								<version>1.0-SNAPSHOT</version>
+								<version>1.1-SNAPSHOT</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
 							<additionalOptions>
diff --git a/pom.xml b/pom.xml
index 4d7baeb..1a1cb7d 100644
--- a/pom.xml
+++ b/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>

From 9b4f7800a32b79e7fbdf9da6e454e68613f6b30a Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:38:10 -0500
Subject: [PATCH 10/13] varIn/varOut fixes

---
 .../java/com/inteligr8/activiti/doclet/MarkdownWriter.java  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
index 8c470bc..47281c7 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
+++ b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
@@ -271,7 +271,7 @@ class MarkdownWriter {
 				matcher = this.namedCommentPattern.matcher(tagComment);
 				if (matcher.find())
 					varInComments.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);
+				else this.logger.warn("A @varIn for the {} bean and {} method is improperly formatted", logId);
 				return;
 			case "varOut":
 				if (varOutComments == null)
@@ -280,7 +280,7 @@ class MarkdownWriter {
 				matcher = this.namedCommentPattern.matcher(tagComment);
 				if (matcher.find())
 					varOutComments.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);
+				else this.logger.warn("A @varOut for the {} bean and {} method is improperly formatted", logId);
 				return;
 			case "throws":
 				if (throwComments == null)
@@ -366,7 +366,7 @@ class MarkdownWriter {
 			varModel.setName(varComment.getKey());
 			varModel.setComment(varComment.getValue());
 
-			sigModel.getVariablesIn().put(varModel.getName(), varModel);
+			sigModel.getVariablesOut().put(varModel.getName(), varModel);
 		}
 	}
 	

From d24aa54e75ef633ce1bcdad84c45b0de39a2af81 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 14:48:23 -0500
Subject: [PATCH 11/13] better delegate @see linking

---
 README.md                                                       | 2 +-
 src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java | 2 +-
 src/main/resources/templates/bean.md.ftl                        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 48f5e9d..4bee719 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ This supports many standard tags used in JavaDoc comments.  This includes suppor
 | `@return`     |                    | ✓       |
 | `@throws`     |                    | ✓       |
 
-If the `@see` tag contains a `#` (e.g. `beanId#method`) then it will hyperlink to the specified bean and method.
+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`.
 
diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
index 47281c7..602d2be 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
+++ b/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;
diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl
index b27f976..feec358 100644
--- a/src/main/resources/templates/bean.md.ftl
+++ b/src/main/resources/templates/bean.md.ftl
@@ -16,7 +16,7 @@
 
 </#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.
 

From 5858f56784434862c6b335824e38f597176c2cc3 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 15:19:08 -0500
Subject: [PATCH 12/13] better detect empty body

---
 src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
index 602d2be..41ec635 100644
--- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
+++ b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java
@@ -222,7 +222,7 @@ 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()));
 	}
 	

From 1d4e323c1203992a4ab0586dcaa6e0722839cb76 Mon Sep 17 00:00:00 2001
From: "Brian M. Long" <brian@inteligr8.com>
Date: Mon, 10 Feb 2025 15:19:20 -0500
Subject: [PATCH 13/13] refactored freemarker spacing

---
 src/main/resources/templates/bean.md.ftl | 72 +++++++++++++-----------
 1 file changed, 38 insertions(+), 34 deletions(-)

diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl
index feec358..64afec1 100644
--- a/src/main/resources/templates/bean.md.ftl
+++ b/src/main/resources/templates/bean.md.ftl
@@ -1,21 +1,25 @@
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
+<#if (tags.author?? || tags.since?? || tags.version?? || tags.deprecated??)>
 
-<#if (tags.author?? || tags.since?? || tags.version?? || tags.deprecated??)><#if tags.author??><#list tags.author as author>
-*Author*: ${author}
-</#list></#if><#if tags.since??>*Since Version*: ${tags.since[0]}
+<#if tags.author??><#list tags.author as author>*Author*: ${author}</#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><#if tags.deprecated??>*Deprecated*</#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>
-
-</#if>
+</#list></#if></#if>
 <#if hasDelegate>
+
 ## <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.
@@ -30,9 +34,9 @@ ${r"${"}${beanId}${r"}"}
 <#if executionListenerMethod??><#assign taskUses = taskUses + ["**Execution Listener**"] /></#if>
 <#if taskListenerMethod??><#assign taskUses = taskUses + ["**Task Listener**"] /></#if>
 You may use it in a ${taskUses?join(" or ")}.
-
 <@sigdoc sig=delegateMethod showParams=false/>
 </#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.
@@ -43,35 +47,31 @@ 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>
+
+---
+
 [Back to Index](index.md)
 
 Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).
 
 <#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 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 sig.docBody??>${sig.docBody}<#else>No documentation available.</#if>
-
 <#if ((showParams && sig.params?size > 0) || sig.bpmnFields?size > 0 || sig.variablesIn?size > 0)>
+
 | Input Type               | Name                     | Java Type                                        | Documentation                      |
 | ------------------------ | ------------------------ | ------------------------------------------------ | ---------------------------------- |
 <#if showParams><#list sig.params as paramName, param>
@@ -87,9 +87,9 @@ Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https:
 | 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??>
@@ -110,14 +110,18 @@ Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https:
 | 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 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>
+</#if>
 </#macro>
\ No newline at end of file