v1.0.3 pom

README.md

@@ -0,0 +1,48 @@
+# 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.
+
+```xml
+<profile>
+	<id>apidocs</id>
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>3.4.1</version>
+				<executions>
+					<execution>
+						<id>generate-doclet</id>
+						<phase>generate-resources</phase>
+						<goals><goal>javadoc</goal></goals>
+						<configuration>
+							<doclet>com.inteligr8.activiti.doclet.ActivitiDoclet</doclet>
+							<docletArtifact>
+								<groupId>com.inteligr8.activiti</groupId>
+								<artifactId>activiti-api-doclet</artifactId>
+								<version>1.0.3</version>
+							</docletArtifact>
+							<useStandardDocletOptions>false</useStandardDocletOptions>
+							<destDir>apidocs</destDir>
+							<reportOutputDirectory>${basedir}</reportOutputDirectory>
+							<additionalOptions>
+								<additionalOption>--title 'API Documentation'</additionalOption>
+								<additionalOption>--apiName '${project.name}</additionalOption>
+							</additionalOptions>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+</profile>
+```
+
+You can generate the docs with the following command:
+
+```
+mvn -Papidocs generate-resources
+```
+
+The documentation will be placed in `<reportOutputDirectory>/<destDir>`.

pom.xml

@@ -4,7 +4,7 @@
     <groupId>com.inteligr8.activiti</groupId>
     <artifactId>activiti-api-doclet</artifactId>
     <packaging>jar</packaging>
-    <version>1.0.0</version>
+    <version>1.0.3</version>
     
     <name>Activiti Doclet</name>
     <description>JavaDoc Doclet for Activiti Extension APIs</description>

src/it/base/pom.xml

@@ -50,10 +50,11 @@
 								<version>@pom.version@</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
-							<destDir>destDir</destDir>
+							<destDir>apidocs</destDir>
+							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
-								<additionalOption>-d d</additionalOption>
+								<additionalOption>--title 'Example Title'</additionalOption>
-								<additionalOption>--flavor bitbucket</additionalOption>
+								<additionalOption>--apiName '${project.name}'</additionalOption>
 							</additionalOptions>
 						</configuration>
 					</execution>

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

@@ -7,6 +7,8 @@ import org.springframework.stereotype.Component;
  * Here is a second line that happens
  * to span multiple lines.
  * 
+ * Here is a {@link http://inteligr8.com} for testing purposes.  And here is another { @link http://inteligr8.com } one.
+ * 
  * @author brian@inteligr8.com
  * @version 1.0
  */
@@ -81,6 +83,12 @@ public class TestNamedBean {
 	 * @param param A parameter comment.
 	 * @return A return comment.
 	 * @throws java.lang.Exception An exception comment.
+	 * @throws org.activiti.engine.delegate.BpmnError http-404
+	 * @throws BpmnError http-400 A client error.
+	 * @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 {
 		return null;

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

@@ -54,9 +54,12 @@ class ActivitiApiBeanDoc {
 		return this;
 	}
 	
+	public List<ExecutableElement> getMethodElements() {
+		return new ArrayList<>(this.methodElements.values());
+	}
+	
 	public List<ExecutableElement> getSortedMethodElements() {
-		List<ExecutableElement> methodElements = new ArrayList<>(this.methodElements.size());
+		List<ExecutableElement> methodElements = this.getMethodElements();
-		methodElements.addAll(this.methodElements.values());
 		Collections.sort(methodElements, new Comparator<ExecutableElement>() {
 			@Override
 			public int compare(ExecutableElement methodElement1, ExecutableElement methodElement2) {

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

@@ -91,7 +91,6 @@ class ActivitiDocFilter {
 
 		// getAllTypeElements() will get inherited interfaces
 		for (TypeMirror interfaceType : classElement.getInterfaces()) {
-			this.logger.info("{} contains {}", beanId, interfaceType);
 			this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);
 			
 			switch (interfaceType.toString()) {

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

@@ -44,8 +44,7 @@ import jdk.javadoc.doclet.Reporter;
 public class ActivitiDoclet implements Doclet {
 	
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
-	private String outputDirectory;
+	
-	private String flavor;
 	private String title;
 	private String apiName;
 	
@@ -57,24 +56,6 @@ public class ActivitiDoclet implements Doclet {
 	@Override
 	public Set<? extends Option> getSupportedOptions() {
 		return new HashSet<>(Arrays.asList(
-			new PathOption("-d", "Destination directory for output files", Kind.STANDARD, "--destDir") {
-				@Override
-				public boolean process(String name, List<String> valueAndClasses) {
-					outputDirectory = valueAndClasses.get(0);
-					return true;
-				}
-			},
-			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) {
@@ -122,13 +103,11 @@ public class ActivitiDoclet implements Doclet {
 		List<ActivitiApiBeanDoc> beandocs = docfilter.build();
 
 		try {
-			MarkdownWriter mdwriter = new MarkdownWriter(docenv, this.outputDirectory);
+			MarkdownWriter mdwriter = new MarkdownWriter(docenv);
 			if (this.title != null)
 				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) {
@@ -193,17 +172,4 @@ public class ActivitiDoclet implements Doclet {
 		
 	}
 
-	private abstract class PathOption extends ValueOption {
-		
-		public PathOption(String name, String description, Kind kind, String... additionalNames) {
-			super(name, description, kind, additionalNames);
-		}
-		
-		@Override
-		public String getParameters() {
-			return "<dir>";
-		}
-		
-	}
-
 }

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

@@ -24,7 +24,7 @@ import java.util.Set;
 /**
  * @author brian@inteligr8.com
  */
-public class BeanFreemarkerModel {
+public class BeanFreemarkerModel implements JavadocDocumentable, JavadocTaggable {
 	
 	private String title;
 	
@@ -32,8 +32,6 @@ public class BeanFreemarkerModel {
 	
 	private String beanId;
 	
-	private String bookmark;
-	
 	private String docFirstSentence;
 
 	private String docBody;
@@ -42,6 +40,8 @@ public class BeanFreemarkerModel {
 
 	private Map<String, List<String>> tags = new LinkedHashMap<>();
 
+	private List<ReferenceFreemarkerModel> seeRefs = new LinkedList<>();
+	
 	private List<MethodFreemarkerModel> methods = new LinkedList<>();
 
 	public String getTitle() {
@@ -68,14 +68,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;
 	}
@@ -108,6 +100,15 @@ public class BeanFreemarkerModel {
 		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/FluentMap.java

@@ -0,0 +1,95 @@
+package com.inteligr8.activiti.doclet;
+
+import java.util.Collection;
+import java.util.Map;
+import java.util.Set;
+
+public class FluentMap<K, V> implements Map<K, V> {
+	
+	private Map<K, V> map;
+	
+	public FluentMap(Map<K, V> map) {
+		this.map = map;
+	}
+	
+	@Override
+	public void clear() {
+		this.map.clear();
+	}
+	
+	@Override
+	public boolean containsKey(Object key) {
+		return this.map.containsKey(key);
+	}
+	
+	@Override
+	public boolean containsValue(Object value) {
+		return this.map.containsValue(value);
+	}
+	
+	@Override
+	public Set<Entry<K, V>> entrySet() {
+		return this.map.entrySet();
+	}
+	
+	@Override
+	public boolean equals(Object obj) {
+		return this.map.equals(obj);
+	}
+	
+	@Override
+	public V get(Object key) {
+		return this.map.get(key);
+	}
+	
+	@Override
+	public int hashCode() {
+		return this.map.hashCode();
+	}
+	
+	@Override
+	public boolean isEmpty() {
+		return this.map.isEmpty();
+	}
+	
+	@Override
+	public Set<K> keySet() {
+		return this.map.keySet();
+	}
+	
+	@Override
+	public V put(K key, V value) {
+		return this.map.put(key, value);
+	}
+	
+	@Override
+	public void putAll(Map<? extends K, ? extends V> m) {
+		this.map.putAll(m);
+	}
+	
+	@Override
+	public V remove(Object key) {
+		return this.map.remove(key);
+	}
+	
+	@Override
+	public int size() {
+		return this.map.size();
+	}
+	
+	@Override
+	public Collection<V> values() {
+		return this.map.values();
+	}
+	
+	public FluentMap<K, V> with(K key, V value) {
+		this.map.put(key, value);
+		return this;
+	}
+	
+	public FluentMap<K, V> without(K key) {
+		this.map.remove(key);
+		return this;
+	}
+
+}

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

@@ -18,11 +18,15 @@ import java.io.File;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.nio.charset.Charset;
+import java.util.Arrays;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -34,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;
@@ -52,24 +54,32 @@ import jdk.javadoc.doclet.DocletEnvironment;
 class MarkdownWriter {
 
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
-	private final Pattern tagPattern = Pattern.compile("@[^ ]+ ?(.*)$");
+	private final Set<String> bpmnErrorSet = new HashSet<>(Arrays.asList(
-	private final Pattern namedTagPattern = Pattern.compile("@[^ ]+ ([^ ]+) ?(.*)$");
+			"BpmnError".toLowerCase(),
+			"org.activiti.engine.delegate.BpmnError".toLowerCase()));
+	
+	private final Pattern tagPattern = Pattern.compile("@([^ ]+) ?(.*)$");
+	private final Pattern namedCommentPattern = Pattern.compile("([^ ]+) ?(.*)$");
+	private final Map<Pattern, String> sanitizations = new FluentMap<>(new LinkedHashMap<Pattern, String>())
+			.with(Pattern.compile("^[ ]+", Pattern.MULTILINE), "")
+			.with(Pattern.compile("\r\n", Pattern.MULTILINE), "\n")
+			.with(Pattern.compile("([^\n])\n([^\n])", Pattern.MULTILINE), "$1 $2")
+			.with(Pattern.compile("([^\\.\\?!])[ ]{2}", Pattern.MULTILINE), "$1 ")
+			.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;
 	private final Configuration fmconfig;
+	
 	private String title = "API Documentation";
 	private String apiName;
-	private String flavor;
 	
-	public MarkdownWriter(DocletEnvironment docenv, String outputDirectory) throws IOException {
+	public MarkdownWriter(DocletEnvironment docenv) throws IOException {
 		this.docenv = docenv;
-		this.outputDirectory = (outputDirectory == null || outputDirectory.trim().length() == 0) ? new File(".") : new File(outputDirectory);
+		this.outputDirectory = new File(".");
-		this.fmconfig = this.getFreemarkerConfiguration();
-	}
-	
-	public MarkdownWriter(DocletEnvironment docenv, File outputDirectory) throws IOException {
-		this.docenv = docenv;
-		this.outputDirectory = outputDirectory == null ? new File(".") : outputDirectory;
 		this.fmconfig = this.getFreemarkerConfiguration();
 	}
 	
@@ -92,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);
 		
@@ -111,7 +117,6 @@ class MarkdownWriter {
 		this.logger.debug("Building documentation index model");
 		
 		IndexFreemarkerModel indexModel = new IndexFreemarkerModel();
-		System.out.println("title: " + this.title);
 		indexModel.setTitle(this.title);
 		indexModel.setApiName(this.apiName);
 
@@ -124,7 +129,6 @@ 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())
@@ -134,126 +138,55 @@ class MarkdownWriter {
 			if (commentTree != null) {
 				this.logger.debug("Found documentation for bean: {}", beandoc.getBeanId());
 				
-				if (commentTree.getFirstSentence() != null)
+				this.buildDocumentation(commentTree, beanModel);
-					beanModel.setDocFirstSentence(commentTree.getFirstSentence().toString());
-				if (commentTree.getBody() != null)
-					beanModel.setDocBody(commentTree.getFullBody().toString());
 				for (DocTree tag : commentTree.getBlockTags()) {
-					String tagName = null;
+					this.buildTagModel(tag, beandoc.getBeanId(),
-					if (tag instanceof BlockTagTree) {
+							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());
 				}
 			}
 
 			Map<Name, MethodFreemarkerModel> methodOverloads = new LinkedHashMap<>();
 			
 			for (ExecutableElement methodElement : beandoc.getSortedMethodElements()) {
+				String logId = beandoc.getBeanId() + "." + methodElement.toString();
 				DocCommentTree methodCommentTree = docs.getDocCommentTree(methodElement);
 
-				this.logger.debug("Building documentation method model: {}.{}", beandoc.getBeanId(), methodElement);
+				this.logger.debug("Building documentation method model: {}", logId);
 				
 				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);
 				}
 				
 				Map<String, String> paramComments = new HashMap<>();
-				Map<String, String> throwComments = new HashMap<>();
+				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 method: {}.{}", beandoc.getBeanId(), methodElement);
+					this.logger.debug("Found documentation for '{}'", logId);
 
-					if (methodCommentTree.getFirstSentence() != null) {
+					this.buildDocumentation(methodCommentTree, sigModel);
 					if (methodModel.getDocFirstSentence() == null)
-							methodModel.setDocFirstSentence(methodCommentTree.getFirstSentence().toString());
+						methodModel.setDocFirstSentence(sigModel.getDocFirstSentence());
-						sigModel.setDocFirstSentence(methodCommentTree.getFirstSentence().toString());
-					}
-					if (methodCommentTree.getBody() != null)
-						sigModel.setDocBody(methodCommentTree.getFullBody().toString());
 					for (DocTree tag : methodCommentTree.getBlockTags()) {
-						String tagName = null;
+						this.buildTagModel(tag, logId,
-						if (tag instanceof BlockTagTree) {
+								paramComments, throwComments, errorComments, sigModel);
-							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 method: {}.{}", tagName, beandoc.getBeanId(), methodElement);
-
-						Matcher matcher;
-						switch (tagName) {
-							case "param":
-								matcher = this.namedTagPattern.matcher(tag.toString());
-								if (matcher.find())
-									paramComments.put(matcher.group(1), matcher.group(2).trim());
-								else this.logger.warn("A @param for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-							case "throws":
-								matcher = this.namedTagPattern.matcher(tag.toString());
-								if (matcher.find())
-									throwComments.put(matcher.group(1), matcher.group(2).trim());
-								else this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-								break;
-							default:
-								matcher = this.tagPattern.matcher(tag.toString());
-								if (matcher.find())
-									this.putAdd(sigModel.getTags(), tagName, matcher.group(1).trim());
-								else this.logger.warn("A '@{}' tag for the {} bean and {} method is improperly formatted", tagName, beanModel.getBeanId(), methodElement);
-						}
 					}
 				}
 				
-				StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("(");
+				this.buildMethodArguments(methodElement, logId, paramComments, sigModel);
+				this.buildMethodThrows(methodElement, logId, throwComments, !errorComments.isEmpty(), sigModel);
+				this.buildMethodErrors(methodElement, logId, errorComments, sigModel);
+				this.buildMethodReturns(methodElement, logId, sigModel);
+				this.buildMethodSignature(methodElement, sigModel);
 
-				for (VariableElement varElement : methodElement.getParameters()) {
+				if (!paramComments.isEmpty())
-					this.logger.trace("Found parameter '{}' for method: {}.{}", varElement.getSimpleName(), beandoc.getBeanId(), methodElement);
+					this.logger.warn("'{}' has documented parameters {} that don't exist; ignoring ...", logId, paramComments.keySet());
-					
-					ParamFreemarkerModel paramModel = new ParamFreemarkerModel();
-					paramModel.setName(varElement.getSimpleName().toString());
-					paramModel.setType(varElement.asType().toString());
-					paramModel.setComment(paramComments.get(paramModel.getName()));
-					
-					sigModel.getParams().put(paramModel.getName(), paramModel);
-					methodSignature.append(varElement.getSimpleName()).append(": ").append(varElement.asType()).append(", ");
-				}
-				
-				for (TypeMirror thrownType : methodElement.getThrownTypes()) {
-					this.logger.trace("Found thrown '{}' for method: {}.{}", thrownType, beandoc.getBeanId(), methodElement);
-					
-					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
-					throwModel.setType(thrownType.toString());
-					throwModel.setComment(throwComments.get(throwModel.getType()));
-					
-					sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
-				}
-
-				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);
 			}
@@ -264,6 +197,135 @@ class MarkdownWriter {
 		return indexModel;
 	}
 	
+	private void buildDocumentation(DocCommentTree commentTree, JavadocDocumentable docuable) {
+		if (commentTree.getFirstSentence() != null)
+			docuable.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
+		if (commentTree.getBody() != null)
+			docuable.setDocBody(this.sanitize(commentTree.getFullBody()));
+	}
+	
+	private void buildTagModel(DocTree tag, String logId,
+			Map<String, String> paramComments,
+			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 "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 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 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("Found 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"));
@@ -286,18 +348,14 @@ class MarkdownWriter {
 		}
 	}
 	
-	private String formatBookmark(String title) {
+	private String sanitize(List<? extends DocTree> docs) {
-		if (this.flavor == null || title == null)
+		return this.sanitize(docs.toString());
-			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(String str) {
+		for (Entry<Pattern, String> sanitize : this.sanitizations.entrySet())
+			str = sanitize.getKey().matcher(str).replaceAll(sanitize.getValue());
+		return str;
 	}
 	
 	private <T> T putAdd(Map<String, List<T>> map, String key, T value) {

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,10 +15,11 @@
 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;
 	
@@ -28,12 +29,16 @@ public class MethodSignatureFreemarkerModel {
 	
 	private Map<String, ThrowFreemarkerModel> throwTypes = new LinkedHashMap<>();
 	
+	private Map<String, ThrowFreemarkerModel> bpmnErrors = new LinkedHashMap<>();
+	
 	private String docFirstSentence;
 
 	private String docBody;
 
 	private Map<String, List<String>> tags = new LinkedHashMap<>();
 
+	private List<ReferenceFreemarkerModel> seeRefs = new LinkedList<>();
+
 	public String getMethodSignature() {
 		return methodSignature;
 	}
@@ -66,6 +71,14 @@ public class MethodSignatureFreemarkerModel {
 		this.throwTypes = throwTypes;
 	}
 	
+	public Map<String, ThrowFreemarkerModel> getBpmnErrors() {
+		return bpmnErrors;
+	}
+	
+	public void setBpmnErrors(Map<String, ThrowFreemarkerModel> bpmnErrors) {
+		this.bpmnErrors = bpmnErrors;
+	}
+
 	public String getDocFirstSentence() {
 		return docFirstSentence;
 	}
@@ -90,4 +103,12 @@ public class MethodSignatureFreemarkerModel {
 		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/resources/templates/bean.md.ftl

@@ -1,19 +1,30 @@
 
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
 
-<#if docBody??>${docBody}<#else>No documentation available.</#if>
+<#if (tags.author?? || tags.since?? || tags.deprecated??)>
-
+<#if tags.author??>
-<#if (tags.author?? || tags.since?? || tags.see?? || tags.deprecated??)>
+<#list tags.author as author>
-<#if tags.author??><#list tags.author as author>
 *Author*: ${author}
-</#list></#if>
+</#list>
+</#if>
 <#if tags.since??>*Since*: ${tags.since[0]}</#if>
-<#if tags.see??><#list tags.see as see>
-*See Also*: ${see}
-</#list></#if>
 <#if tags.deprecated??>*Deprecated*</#if>
 
-</#if><#if (delegateRoles?size > 0)>
+</#if>
+<#if docBody??>${docBody}<#else>No documentation available.</#if>
+
+<#if (tags.see?? || seeRefs?size > 0)>
+<#list seeRefs as seeRef>
+*See Also*: [`${seeRef.beanId}.${seeRef.methodName}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
+</#list>
+<#if tags.see??>
+<#list tags.see as see>
+*See Also*: ${see}
+</#list>
+</#if>
+
+</#if>
+<#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.
@@ -38,49 +49,68 @@ This bean and its methods may be used in any "Expression" field or script in a S
 | Method Name                       | Brief Documentation      |
 | --------------------------------- | ------------------------ |
 <#list methods as method>
-	<#assign nameColumn = "[`${method.methodName}`](#${method.bookmark})">
+	<#assign nameColumn = "[`${method.methodName}`](#${method.methodName})">
 | ${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}`**
 
+<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.deprecated??)>
+<#if sig.tags.author??>
+<#list sig.tags.author as author>
+*Author*: ${author}
+</#list>
+</#if>
+<#if sig.tags.since??>*Since*: ${sig.tags.since[0]}</#if>
+<#if sig.tags.deprecated??>*Deprecated*</#if>
+
+</#if>
 <#if sig.docBody??>${sig.docBody}<#else>No documentation available.</#if>
 
 <#if (sig.params?size > 0)>
 | Parameter Name           | Java Type                                        | Documentation            |
 | ------------------------ | ------------------------------------------------ | ------------------------ |
 <#list sig.params as paramName, param>
-| ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if param.comment??>${param.comment?right_pad(24)}<#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.returnType?? || sig.throwTypes?size > 0)>
-| Result Type              | Java Type                                        | Documentation            |
+| Result Type              | Java Type or BPMN Error Code                     | Documentation            |
 | ------------------------ | ------------------------------------------------ | ------------------------ |
 <#if sig.returnType??>
-| Return Value             | ${("`" + sig.returnType + "`")?right_pad(48)} | <#if sig.tags.return??>${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(24)}<#else>No documentation available.</#if> |
 </#if>
 <#if (sig.throwTypes?size > 0)>
 <#list sig.throwTypes as throwType, throw>
-| Thrown Exception         | ${("`" + throwType + "`")?right_pad(48)} | <#if throw.comment??>${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(24)}<#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> |
 </#list>
 </#if>
 
 </#if>
-<#if (sig.tags.author?? || sig.tags.since?? || sig.tags.see?? || sig.tags.deprecated??)>
+<#if (sig.tags.see?? || sig.seeRefs?size > 0)>
-<#if sig.tags.author??><#list sig.tags.author as author>
+<#list sig.seeRefs as seeRef>
-*Author*: ${author}
+*See Also*: [`${seeRef.beanId}.${seeRef.methodName}`](bean-${seeRef.beanId}.md#${seeRef.methodName})
-</#list></#if>
+</#list>
-<#if sig.tags.since??>*Since*: ${sig.tags.since[0]}</#if>
+<#if sig.tags.see??>
-<#if sig.tags.see??><#list sig.tags.see as see>
+<#list sig.tags.see as see>
 *See Also*: ${see}
-</#list></#if>
+</#list>
-<#if sig.tags.deprecated??>*Deprecated*</#if>
+</#if>
 
 </#if>
 </#list>
 </#list>
+
+---
+
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).

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

@@ -25,3 +25,7 @@ It is important to note that Activiti expressions use the JUEL language and Acti
 	<#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>
+
+---
+
+Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).