@see improvements, bookmarking, and other fixes

README.md

@@ -21,13 +21,12 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
 							<docletArtifact>
 								<groupId>com.inteligr8.activiti</groupId>
 								<artifactId>activiti-api-doclet</artifactId>
-								<version>1.0.1</version>
+								<version>1.0.3</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
 							<destDir>apidocs</destDir>
 							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
-								<additionalOption>--flavor bitbucket</additionalOption>
 								<additionalOption>--title 'API Documentation'</additionalOption>
 								<additionalOption>--apiName '${project.name}</additionalOption>
 							</additionalOptions>

src/it/base/pom.xml

@@ -53,7 +53,6 @@
 							<destDir>apidocs</destDir>
 							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
-								<additionalOption>--flavor bitbucket</additionalOption>
 								<additionalOption>--title 'Example Title'</additionalOption>
 								<additionalOption>--apiName '${project.name}'</additionalOption>
 							</additionalOptions>

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

@@ -85,7 +85,9 @@ public class TestNamedBean {
 	 * @throws java.lang.Exception An exception comment.
 	 * @throws org.activiti.engine.delegate.BpmnError http-404
 	 * @throws BpmnError http-400 A client error.
-	 * @see `test.bean`
+	 * @see test-sub.apiMethod10
+	 * @see {@link http://inteligr8.com}
+	 * @see [Inteligr8](http://inteligr8.com)
 	 * @see http://inteligr8.com
 	 */
 	public String apiMethod8(String param) throws Exception {

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

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

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

@@ -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/JavadocDocumentable.java

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

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

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

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

@@ -38,10 +38,8 @@ import javax.lang.model.type.TypeMirror;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.sun.source.doctree.BlockTagTree;
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
-import com.sun.source.doctree.InlineTagTree;
 import com.sun.source.util.DocTrees;
 
 import freemarker.template.Configuration;
@@ -70,6 +68,7 @@ class MarkdownWriter {
 			.with(Pattern.compile("\\{ ?(@[^}]+) \\}"), "{$1}")
 			.with(Pattern.compile("\\{@link ([^}]+)\\}"), "[$1]($1)")
 			.with(Pattern.compile("([A-Za-z0-9\\-\\._]+@[A-Za-z0-9\\-\\._]+)"), "[$1](mailto:$1)");
+	private final Pattern seeRefPattern = Pattern.compile("^([A-Za-z0-9_\\-]+)\\.([A-Za-z0-9_]+)$");
 	
 	private final DocletEnvironment docenv;
 	private final File outputDirectory;
@@ -77,7 +76,6 @@ class MarkdownWriter {
 	
 	private String title = "API Documentation";
 	private String apiName;
-	private String flavor;
 	
 	public MarkdownWriter(DocletEnvironment docenv) throws IOException {
 		this.docenv = docenv;
@@ -104,10 +102,6 @@ class MarkdownWriter {
 		this.apiName = apiName;
 	}
 	
-	public void setFlavor(String flavor) {
-		this.flavor = flavor;
-	}
-	
 	public void write(List<ActivitiApiBeanDoc> beandocs) throws IOException, TemplateException {
 		IndexFreemarkerModel model = this.buildModel(beandocs);
 		
@@ -135,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())
@@ -145,38 +138,25 @@ class MarkdownWriter {
 			if (commentTree != null) {
 				this.logger.debug("Found documentation for bean: {}", beandoc.getBeanId());
 				
-				if (commentTree.getFirstSentence() != null)
+				this.buildDocumentation(commentTree, beanModel);
-					beanModel.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
-				if (commentTree.getBody() != null)
-					beanModel.setDocBody(this.sanitize(commentTree.getFullBody()));
 				for (DocTree tag : commentTree.getBlockTags()) {
-					String tagName = null;
+					this.buildTagModel(tag, beandoc.getBeanId(),
-					if (tag instanceof BlockTagTree) {
+							null, null, null, 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);
@@ -188,116 +168,25 @@ class MarkdownWriter {
 				
 				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);
-						sigModel.setDocFirstSentence(this.sanitize(methodCommentTree.getFirstSentence()));
 					if (methodModel.getDocFirstSentence() == null)
 						methodModel.setDocFirstSentence(sigModel.getDocFirstSentence());
-					}
-					if (methodCommentTree.getBody() != null)
-						sigModel.setDocBody(this.sanitize(methodCommentTree.getFullBody()));
 					for (DocTree tag : methodCommentTree.getBlockTags()) {
-						Matcher matcher = this.tagPattern.matcher(tag.toString());
+						this.buildTagModel(tag, logId,
-						if (!matcher.find()) {
+								paramComments, throwComments, errorComments, sigModel);
-							this.logger.warn("A tag for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-							continue;
-						}
-						
-						String tagName = matcher.group(1);
-						String tagComment = matcher.group(2).trim();
-
-						this.logger.info("Found tag '{}' for method: {}.{}", tagName, beandoc.getBeanId(), methodElement);
-
-						switch (tagName) {
-							case "param":
-								matcher = this.namedCommentPattern.matcher(tagComment);
-								if (matcher.find())
-									paramComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
-								else this.logger.warn("A @param for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-								break;
-							case "throws":
-								matcher = this.namedCommentPattern.matcher(tagComment);
-								if (matcher.find()) {
-									if (this.bpmnErrorSet.contains(matcher.group(1).toLowerCase())) {
-										Matcher ecmatcher = this.namedCommentPattern.matcher(matcher.group(2).trim());
-										if (ecmatcher.find()) {
-											errorComments.put(ecmatcher.group(1), this.sanitize(ecmatcher.group(2).trim()));
-										} else {
-											this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-										}
-									} else {
-										throwComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
-									}
-								}
-								else this.logger.warn("A @throws for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
-								break;
-							default:
-								this.putAdd(sigModel.getTags(), tagName, this.sanitize(tagComment));
-						}
 					}
 				}
 				
-				StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("(");
+				this.buildMethodArguments(methodElement, logId, paramComments, sigModel);
-				
+				this.buildMethodThrows(methodElement, logId, throwComments, !errorComments.isEmpty(), sigModel);
-				for (VariableElement varElement : methodElement.getParameters()) {
+				this.buildMethodErrors(methodElement, logId, errorComments, sigModel);
-					this.logger.trace("Found parameter '{}' for method: {}.{}", varElement.getSimpleName(), beandoc.getBeanId(), methodElement);
+				this.buildMethodReturns(methodElement, logId, sigModel);
-					
+				this.buildMethodSignature(methodElement, sigModel);
-					ParamFreemarkerModel paramModel = new ParamFreemarkerModel();
-					paramModel.setName(varElement.getSimpleName().toString());
-					paramModel.setType(varElement.asType().toString());
-					paramModel.setComment(paramComments.remove(paramModel.getName()));
-					
-					sigModel.getParams().put(paramModel.getName(), paramModel);
-					methodSignature.append(varElement.getSimpleName()).append(": ").append(varElement.asType()).append(", ");
-				}
 
 				if (!paramComments.isEmpty())
-					this.logger.warn("The {} bean and {} method has documented parameters that don't exist; ignoring ...", beandoc.getBeanId(), methodElement);
+					this.logger.warn("'{}' has documented parameters {} that don't exist; ignoring ...", logId, paramComments.keySet());
-				
-				for (TypeMirror thrownType : methodElement.getThrownTypes()) {
-					this.logger.trace("Found thrown '{}' for method: {}.{}", thrownType, beandoc.getBeanId(), methodElement);
-					
-					if ("org.activiti.engine.delegate.BpmnError".equals(thrownType.toString()) && !errorComments.isEmpty())
-						continue;
-					
-					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
-					throwModel.setType(thrownType.toString());
-					throwModel.setComment(throwComments.remove(throwModel.getType()));
-					
-					sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
-				}
-				
-				for (Entry<String, String> throwComment : throwComments.entrySet()) {
-					this.logger.trace("Found documented but not declared thrown '{}' for method: {}.{}", throwComment.getKey(), beandoc.getBeanId(), methodElement);
-
-					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
-					throwModel.setType(throwComment.getKey());
-					throwModel.setComment(throwComment.getValue());
-					
-					sigModel.getThrowTypes().put(throwModel.getType(), throwModel);
-				}
-				
-				for (Entry<String, String> errorComment : errorComments.entrySet()) {
-					this.logger.trace("Found BPMN error thrown code '{}' for method: {}.{}", errorComment.getKey(), beandoc.getBeanId(), methodElement);
-
-					ThrowFreemarkerModel errorModel = new ThrowFreemarkerModel();
-					errorModel.setType(errorComment.getKey());
-					errorModel.setComment(errorComment.getValue());
-					
-					sigModel.getBpmnErrors().put(errorModel.getType(), errorModel);
-				}
-
-				this.logger.trace("Found return '{}' for method: {}.{}", methodElement.getReturnType(), beandoc.getBeanId(), methodElement);
-				if (!"void".equals(methodElement.getReturnType().toString()))
-					sigModel.setReturnType(methodElement.getReturnType().toString());
-				
-				if (methodSignature.charAt(methodSignature.length()-1) != '(')
-					methodSignature.delete(methodSignature.length()-2, methodSignature.length());
-				methodSignature.append("): ").append(methodElement.getReturnType());
-				
-				this.logger.debug("Found method signature: {}", methodSignature);
-				sigModel.setMethodSignature(methodSignature.toString());
 				
 				methodModel.getSignatures().add(sigModel);
 			}
@@ -308,6 +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"));
@@ -330,20 +348,6 @@ class MarkdownWriter {
 		}
 	}
 	
-	private String formatBookmark(String title) {
-		if (this.flavor == null || title == null)
-			return null;
-		
-		switch (this.flavor.toLowerCase()) {
-			case "github":
-				return title.toLowerCase().replaceAll(" ", "-");
-			case "bitbucket":
-				return "markdown-header-" + title.toLowerCase().replaceAll(" ", "-");
-			default:
-				return null;
-		}
-	}
-	
 	private String sanitize(List<? extends DocTree> docs) {
 		return this.sanitize(docs.toString());
 	}

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

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

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

@@ -15,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;
 	
@@ -36,6 +37,8 @@ public class MethodSignatureFreemarkerModel {
 
 	private Map<String, List<String>> tags = new LinkedHashMap<>();
 
+	private List<ReferenceFreemarkerModel> seeRefs = new LinkedList<>();
+
 	public String getMethodSignature() {
 		return methodSignature;
 	}
@@ -100,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

@@ -2,18 +2,26 @@
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
 
 <#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></#if>
+</#list>
+</#if>
 <#if tags.since??>*Since*: ${tags.since[0]}</#if>
 <#if tags.deprecated??>*Deprecated*</#if>
 
 </#if>
 <#if docBody??>${docBody}<#else>No documentation available.</#if>
 
-<#if tags.see??><#list tags.see as see>
+<#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)>
@@ -41,20 +49,22 @@ 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>
+<#if sig.tags.author??>
+<#list sig.tags.author as author>
 *Author*: ${author}
-</#list></#if>
+</#list>
+</#if>
 <#if sig.tags.since??>*Since*: ${sig.tags.since[0]}</#if>
 <#if sig.tags.deprecated??>*Deprecated*</#if>
 
@@ -87,10 +97,20 @@ This bean and its methods may be used in any "Expression" field or script in a S
 </#if>
 
 </#if>
-<#if sig.tags.see??><#list sig.tags.see as see>
+<#if (sig.tags.see?? || sig.seeRefs?size > 0)>
+<#list sig.seeRefs as seeRef>
+*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>
 </#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).