diff --git a/README.md b/README.md index ee4dd59..0b30af8 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,12 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume com.inteligr8.activiti activiti-api-doclet - 1.0.1 + 1.0.3 false apidocs ${basedir} - --flavor bitbucket --title 'API Documentation' --apiName '${project.name} diff --git a/src/it/base/pom.xml b/src/it/base/pom.xml index cccac76..66b0cdb 100644 --- a/src/it/base/pom.xml +++ b/src/it/base/pom.xml @@ -53,7 +53,6 @@ apidocs ${basedir} - --flavor bitbucket --title 'Example Title' --apiName '${project.name}' diff --git a/src/it/base/src/main/java/TestNamedBean.java b/src/it/base/src/main/java/TestNamedBean.java index e4cf7f0..451885c 100644 --- a/src/it/base/src/main/java/TestNamedBean.java +++ b/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 { diff --git a/src/main/java/com/inteligr8/activiti/doclet/ActivitiDoclet.java b/src/main/java/com/inteligr8/activiti/doclet/ActivitiDoclet.java index 90a7781..099f537 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/ActivitiDoclet.java +++ b/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 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 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 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) { diff --git a/src/main/java/com/inteligr8/activiti/doclet/BeanFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/BeanFreemarkerModel.java index 48985d1..2c630a1 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/BeanFreemarkerModel.java +++ b/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; @@ -41,6 +39,8 @@ public class BeanFreemarkerModel { private Set delegateRoles = new HashSet<>(); private Map> tags = new LinkedHashMap<>(); + + private List seeRefs = new LinkedList<>(); private List methods = new LinkedList<>(); @@ -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; } @@ -107,6 +99,15 @@ public class BeanFreemarkerModel { public void setTags(Map> tags) { this.tags = tags; } + + @Override + public List getSeeRefs() { + return seeRefs; + } + + public void setSeeRefs(List seeRefs) { + this.seeRefs = seeRefs; + } public List getMethods() { return methods; diff --git a/src/main/java/com/inteligr8/activiti/doclet/JavadocDocumentable.java b/src/main/java/com/inteligr8/activiti/doclet/JavadocDocumentable.java new file mode 100644 index 0000000..a8e1e8b --- /dev/null +++ b/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 . + */ +package com.inteligr8.activiti.doclet; + +/** + * @author brian@inteligr8.com + */ +public interface JavadocDocumentable { + + String getDocFirstSentence(); + + void setDocFirstSentence(String docFirstSentence); + + String getDocBody(); + + void setDocBody(String docBody); + +} diff --git a/src/main/java/com/inteligr8/activiti/doclet/JavadocTaggable.java b/src/main/java/com/inteligr8/activiti/doclet/JavadocTaggable.java new file mode 100644 index 0000000..943261c --- /dev/null +++ b/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 . + */ +package com.inteligr8.activiti.doclet; + +import java.util.List; +import java.util.Map; + +/** + * @author brian@inteligr8.com + */ +public interface JavadocTaggable { + + Map> getTags(); + + List getSeeRefs(); + +} diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java index bc0a9ef..8bb90e5 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java +++ b/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 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) - beanModel.setDocFirstSentence(this.sanitize(commentTree.getFirstSentence())); - if (commentTree.getBody() != null) - beanModel.setDocBody(this.sanitize(commentTree.getFullBody())); + this.buildDocumentation(commentTree, beanModel); for (DocTree tag : commentTree.getBlockTags()) { - 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; - } - - this.logger.trace("Found tag '{}' for bean: {}", tagName, beandoc.getBeanId()); - this.putAdd(beanModel.getTags(), tagName, tag.toString()); + this.buildTagModel(tag, beandoc.getBeanId(), + null, null, null, beanModel); } } Map 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); - - if (methodCommentTree.getFirstSentence() != null) { - sigModel.setDocFirstSentence(this.sanitize(methodCommentTree.getFirstSentence())); - if (methodModel.getDocFirstSentence() == null) - methodModel.setDocFirstSentence(sigModel.getDocFirstSentence()); - } - if (methodCommentTree.getBody() != null) - sigModel.setDocBody(this.sanitize(methodCommentTree.getFullBody())); + this.logger.debug("Found documentation for '{}'", logId); + + this.buildDocumentation(methodCommentTree, sigModel); + if (methodModel.getDocFirstSentence() == null) + methodModel.setDocFirstSentence(sigModel.getDocFirstSentence()); 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); - 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)); - } + this.buildTagModel(tag, logId, + paramComments, throwComments, errorComments, sigModel); } } - StringBuilder methodSignature = new StringBuilder(methodElement.getSimpleName()).append("("); - - for (VariableElement varElement : methodElement.getParameters()) { - this.logger.trace("Found parameter '{}' for method: {}.{}", varElement.getSimpleName(), beandoc.getBeanId(), methodElement); - - 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(", "); - } - + 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); + 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())); - - sigModel.getThrowTypes().put(throwModel.getType(), throwModel); - } - - for (Entry 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 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()); + this.logger.warn("'{}' has documented parameters {} that don't exist; ignoring ...", logId, paramComments.keySet()); 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 paramComments, + Map throwComments, + Map 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 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 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 errorComments, MethodSignatureFreemarkerModel sigModel) { + for (Entry 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 docs) { return this.sanitize(docs.toString()); } diff --git a/src/main/java/com/inteligr8/activiti/doclet/MethodFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/MethodFreemarkerModel.java index 7cbd05f..f219a94 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/MethodFreemarkerModel.java +++ b/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 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; } diff --git a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java index 7c8ab74..df6e454 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java +++ b/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> tags = new LinkedHashMap<>(); + private List seeRefs = new LinkedList<>(); + public String getMethodSignature() { return methodSignature; } @@ -99,5 +102,13 @@ public class MethodSignatureFreemarkerModel { public void setTags(Map> tags) { this.tags = tags; } + + public List getSeeRefs() { + return seeRefs; + } + + public void setSeeRefs(List seeRefs) { + this.seeRefs = seeRefs; + } } diff --git a/src/main/java/com/inteligr8/activiti/doclet/ReferenceFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/ReferenceFreemarkerModel.java new file mode 100644 index 0000000..f8e5183 --- /dev/null +++ b/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 . + */ +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; + } + +} diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl index f699851..d85eb61 100644 --- a/src/main/resources/templates/bean.md.ftl +++ b/src/main/resources/templates/bean.md.ftl @@ -2,18 +2,26 @@ # ${title}<#if apiName??>: ${apiName}: `${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} - + + <#if tags.since??>*Since*: ${tags.since[0]} <#if tags.deprecated??>*Deprecated* <#if docBody??>${docBody}<#else>No documentation available. -<#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}) + +<#if tags.see??> +<#list tags.see as see> *See Also*: ${see} + <#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. | <#list methods as method> -### `${method.methodName}` +## `${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} - + + <#if sig.tags.since??>*Since*: ${sig.tags.since[0]} <#if sig.tags.deprecated??>*Deprecated* @@ -87,10 +97,20 @@ This bean and its methods may be used in any "Expression" field or script in a S -<#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}) + +<#if sig.tags.see??> +<#list sig.tags.see as see> *See Also*: ${see} + + +--- + +Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet). diff --git a/src/main/resources/templates/index.md.ftl b/src/main/resources/templates/index.md.ftl index 7e15be0..c1e9008 100644 --- a/src/main/resources/templates/index.md.ftl +++ b/src/main/resources/templates/index.md.ftl @@ -24,4 +24,8 @@ It is important to note that Activiti expressions use the JUEL language and Acti <#list beans as bean> <#assign idColumn = "[`${bean.beanId}`](bean-${bean.beanId}.md)"> | ${idColumn?right_pad(32)} | <#if bean.docFirstSentence??>${bean.docFirstSentence?right_pad(24)}<#else>No documentation available. | - \ No newline at end of file + + +--- + +Generated by the [Inteligr8](https://inteligr8.com) [Activiti API Doclet](https://bitbucket.org/inteligr8/activiti-api-doclet).