v1.0.1 pom

README.md

@@ -21,12 +21,21 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume
 							<docletArtifact>
 								<groupId>com.inteligr8.activiti</groupId>
 								<artifactId>activiti-api-doclet</artifactId>
+<<<<<<< HEAD
+								<version>1.0.0</version>
+							</docletArtifact>
+							<useStandardDocletOptions>false</useStandardDocletOptions>
+							<destDir>destDir</destDir>
+							<additionalOptions>
+								<additionalOption>-d d</additionalOption>
+=======
 								<version>1.0.1</version>
 							</docletArtifact>
 							<useStandardDocletOptions>false</useStandardDocletOptions>
 							<destDir>apidocs</destDir>
 							<reportOutputDirectory>${basedir}</reportOutputDirectory>
 							<additionalOptions>
+>>>>>>> develop
 								<additionalOption>--flavor bitbucket</additionalOption>
 								<additionalOption>--title 'API Documentation'</additionalOption>
 								<additionalOption>--apiName '${project.name}</additionalOption>
@@ -46,4 +55,8 @@ You can generate the docs with the following command:
 mvn -Papidocs generate-resources
 ```
 
+<<<<<<< HEAD
+The documentation is always generated relative to the `target/site/apidocs` directory.  Hopefully that can be fixed in the future.
+=======
 The documentation will be placed in `<reportOutputDirectory>/<destDir>`.
+>>>>>>> develop

pom.xml

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

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

@@ -7,8 +7,6 @@ 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
  */
@@ -83,10 +81,6 @@ 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.bean`
-	 * @see http://inteligr8.com
 	 */
 	public String apiMethod8(String param) throws Exception {
 		return null;

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

@@ -54,12 +54,9 @@ class ActivitiApiBeanDoc {
 		return this;
 	}
 	
-	public List<ExecutableElement> getMethodElements() {
-		return new ArrayList<>(this.methodElements.values());
-	}
-	
 	public List<ExecutableElement> getSortedMethodElements() {
-		List<ExecutableElement> methodElements = this.getMethodElements();
+		List<ExecutableElement> methodElements = new ArrayList<>(this.methodElements.size());
+		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,6 +91,7 @@ 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/FluentMap.java

@@ -1,95 +0,0 @@
-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/MarkdownWriter.java

@@ -18,15 +18,11 @@ 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;
 
@@ -56,25 +52,11 @@ import jdk.javadoc.doclet.DocletEnvironment;
 class MarkdownWriter {
 
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
-	private final Set<String> bpmnErrorSet = new HashSet<>(Arrays.asList(
-			"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 tagPattern = Pattern.compile("@[^ ]+ ?(.*)$");
+	private final Pattern namedTagPattern = Pattern.compile("@[^ ]+ ([^ ]+) ?(.*)$");
 	private final DocletEnvironment docenv;
 	private final File outputDirectory;
 	private final Configuration fmconfig;
-	
 	private String title = "API Documentation";
 	private String apiName;
 	private String flavor;
@@ -146,9 +128,9 @@ class MarkdownWriter {
 				this.logger.debug("Found documentation for bean: {}", beandoc.getBeanId());
 				
 				if (commentTree.getFirstSentence() != null)
-					beanModel.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence()));
+					beanModel.setDocFirstSentence(commentTree.getFirstSentence().toString());
 				if (commentTree.getBody() != null)
-					beanModel.setDocBody(this.sanitize(commentTree.getFullBody()));
+					beanModel.setDocBody(commentTree.getFullBody().toString());
 				for (DocTree tag : commentTree.getBlockTags()) {
 					String tagName = null;
 					if (tag instanceof BlockTagTree) {
@@ -183,57 +165,50 @@ class MarkdownWriter {
 				}
 				
 				Map<String, String> paramComments = new HashMap<>();
-				Map<String, String> throwComments = new LinkedHashMap<>();
-				Map<String, String> errorComments = new LinkedHashMap<>();
+				Map<String, String> throwComments = new HashMap<>();
 				
 				MethodSignatureFreemarkerModel sigModel = new MethodSignatureFreemarkerModel();
 				if (methodCommentTree != null) {
 					this.logger.debug("Found documentation for method: {}.{}", beandoc.getBeanId(), methodElement);
 					
 					if (methodCommentTree.getFirstSentence() != null) {
-						sigModel.setDocFirstSentence(this.sanitize(methodCommentTree.getFirstSentence()));
 						if (methodModel.getDocFirstSentence() == null)
-							methodModel.setDocFirstSentence(sigModel.getDocFirstSentence());
+							methodModel.setDocFirstSentence(methodCommentTree.getFirstSentence().toString());
+						sigModel.setDocFirstSentence(methodCommentTree.getFirstSentence().toString());
 					}
 					if (methodCommentTree.getBody() != null)
-						sigModel.setDocBody(this.sanitize(methodCommentTree.getFullBody()));
+						sigModel.setDocBody(methodCommentTree.getFullBody().toString());
 					for (DocTree tag : methodCommentTree.getBlockTags()) {
-						Matcher matcher = this.tagPattern.matcher(tag.toString());
-						if (!matcher.find()) {
-							this.logger.warn("A tag for the {} bean and {} method is improperly formatted", beanModel.getBeanId(), methodElement);
+						String tagName = null;
+						if (tag instanceof BlockTagTree) {
+							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;
 						}
-						
-						String tagName = matcher.group(1);
-						String tagComment = matcher.group(2).trim();
 
-						this.logger.info("Found tag '{}' for method: {}.{}", tagName, beandoc.getBeanId(), methodElement);
+						this.logger.trace("Found tag '{}' for method: {}.{}", tagName, beandoc.getBeanId(), methodElement);
 
+						Matcher matcher;
 						switch (tagName) {
 							case "param":
-								matcher = this.namedCommentPattern.matcher(tagComment);
+								matcher = this.namedTagPattern.matcher(tag.toString());
 								if (matcher.find())
-									paramComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim()));
+									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);
-								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()));
-									}
-								}
+								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:
-								this.putAdd(sigModel.getTags(), tagName, this.sanitize(tagComment));
+								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);
 						}
 					}
 				}
@@ -246,47 +221,21 @@ class MarkdownWriter {
 					ParamFreemarkerModel paramModel = new ParamFreemarkerModel();
 					paramModel.setName(varElement.getSimpleName().toString());
 					paramModel.setType(varElement.asType().toString());
-					paramModel.setComment(paramComments.remove(paramModel.getName()));
+					paramModel.setComment(paramComments.get(paramModel.getName()));
 					
 					sigModel.getParams().put(paramModel.getName(), paramModel);
 					methodSignature.append(varElement.getSimpleName()).append(": ").append(varElement.asType()).append(", ");
 				}
 				
-				if (!paramComments.isEmpty())
-					this.logger.warn("The {} bean and {} method has documented parameters that don't exist; ignoring ...", beandoc.getBeanId(), methodElement);
-				
 				for (TypeMirror thrownType : methodElement.getThrownTypes()) {
 					this.logger.trace("Found thrown '{}' for method: {}.{}", thrownType, beandoc.getBeanId(), methodElement);
 					
-					if ("org.activiti.engine.delegate.BpmnError".equals(thrownType.toString()) && !errorComments.isEmpty())
-						continue;
-					
 					ThrowFreemarkerModel throwModel = new ThrowFreemarkerModel();
 					throwModel.setType(thrownType.toString());
-					throwModel.setComment(throwComments.remove(throwModel.getType()));
+					throwModel.setComment(throwComments.get(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()))
@@ -344,16 +293,6 @@ class MarkdownWriter {
 		}
 	}
 	
-	private String sanitize(List<? extends DocTree> docs) {
-		return this.sanitize(docs.toString());
-	}
-	
-	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) {
 		List<T> values = map.get(key);
 		if (values == null)

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

@@ -28,8 +28,6 @@ public class MethodSignatureFreemarkerModel {
 	
 	private Map<String, ThrowFreemarkerModel> throwTypes = new LinkedHashMap<>();
 	
-	private Map<String, ThrowFreemarkerModel> bpmnErrors = new LinkedHashMap<>();
-	
 	private String docFirstSentence;
 
 	private String docBody;
@@ -67,14 +65,6 @@ public class MethodSignatureFreemarkerModel {
 	public void setThrowTypes(Map<String, ThrowFreemarkerModel> throwTypes) {
 		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;

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

@@ -1,22 +1,19 @@
 
 # ${title}<#if apiName??>: ${apiName}</#if>: `${beanId}`
 
-<#if (tags.author?? || tags.since?? || tags.deprecated??)>
+<#if docBody??>${docBody}<#else>No documentation available.</#if>
+
+<#if (tags.author?? || tags.since?? || tags.see?? || tags.deprecated??)>
 <#if tags.author??><#list tags.author as author>
 *Author*: ${author}
 </#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>
 *See Also*: ${see}
-</#list>
+</#list></#if>
+<#if tags.deprecated??>*Deprecated*</#if>
 
-</#if>
-<#if (delegateRoles?size > 0)>
+</#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.
@@ -51,45 +48,38 @@ 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??)>
-<#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?length > 0)>${param.comment?right_pad(24)}<#else>No documentation available.</#if> |
+| ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if param.comment??>${param.comment?right_pad(24)}<#else>No documentation available.</#if> |
 </#list>
 
 </#if>
 <#if (sig.returnType?? || sig.throwTypes?size > 0)>
-| Result Type              | Java Type or BPMN Error Code                     | Documentation            |
+| Result Type              | Java Type                                        | 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]?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?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> |
+| Thrown Exception         | ${("`" + throwType + "`")?right_pad(48)} | <#if throw.comment??>${throw.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.author??><#list sig.tags.author as author>
+*Author*: ${author}
+</#list></#if>
+<#if sig.tags.since??>*Since*: ${sig.tags.since[0]}</#if>
 <#if sig.tags.see??><#list sig.tags.see as see>
 *See Also*: ${see}
-</#list>
+</#list></#if>
+<#if sig.tags.deprecated??>*Deprecated*</#if>
 
 </#if>
 </#list>