From 0886a273e41f979a166445d5a44938a3304c1dc9 Mon Sep 17 00:00:00 2001 From: "Brian M. Long" Date: Mon, 10 Feb 2025 11:10:15 -0500 Subject: [PATCH] added @field @varIn @varOut --- .../activiti/doclet/FieldFreemarkerModel.java | 42 ++++++++++ .../activiti/doclet/MarkdownWriter.java | 79 ++++++++++++++++++- .../MethodSignatureFreemarkerModel.java | 30 +++++++ .../activiti/doclet/VarFreemarkerModel.java | 42 ++++++++++ src/main/resources/templates/bean.md.ftl | 31 ++++++-- 5 files changed, 214 insertions(+), 10 deletions(-) create mode 100644 src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java create mode 100644 src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java diff --git a/src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java new file mode 100644 index 0000000..442778e --- /dev/null +++ b/src/main/java/com/inteligr8/activiti/doclet/FieldFreemarkerModel.java @@ -0,0 +1,42 @@ +/* + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or (at your + * option) any later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along + * with this program. If not, see . + */ +package com.inteligr8.activiti.doclet; + +/** + * @author brian@inteligr8.com + */ +public class FieldFreemarkerModel { + + private String name; + + private String comment; + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getComment() { + return comment; + } + + public void setComment(String comment) { + this.comment = comment; + } + +} diff --git a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java index 3a83c59..8c470bc 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java +++ b/src/main/java/com/inteligr8/activiti/doclet/MarkdownWriter.java @@ -135,7 +135,7 @@ class MarkdownWriter { this.buildDocumentation(commentTree, beanModel); for (DocTree tag : commentTree.getBlockTags()) { this.buildTagModel(tag, beandoc.getBeanId(), - null, null, null, beanModel); + null, null, null, null, null, null, beanModel); } } @@ -186,6 +186,9 @@ class MarkdownWriter { this.logger.debug("Building documentation method model: {}", logId); Map paramComments = new HashMap<>(); + Map fieldComments = new LinkedHashMap<>(); + Map varInComments = new LinkedHashMap<>(); + Map varOutComments = new LinkedHashMap<>(); Map throwComments = new LinkedHashMap<>(); Map errorComments = new LinkedHashMap<>(); @@ -196,11 +199,14 @@ class MarkdownWriter { this.buildDocumentation(methodCommentTree, sigModel); for (DocTree tag : methodCommentTree.getBlockTags()) { this.buildTagModel(tag, logId, - paramComments, throwComments, errorComments, sigModel); + paramComments, fieldComments, varInComments, varOutComments, throwComments, errorComments, sigModel); } } this.buildMethodArguments(methodElement, logId, paramComments, sigModel); + this.buildMethodFields(methodElement, logId, fieldComments, sigModel); + this.buildMethodVariablesIn(methodElement, logId, varInComments, sigModel); + this.buildMethodVariablesOut(methodElement, logId, varOutComments, sigModel); this.buildMethodThrows(methodElement, logId, throwComments, !errorComments.isEmpty(), sigModel); this.buildMethodErrors(methodElement, logId, errorComments, sigModel); this.buildMethodReturns(methodElement, logId, sigModel); @@ -222,6 +228,9 @@ class MarkdownWriter { private void buildTagModel(DocTree tag, String logId, Map paramComments, + Map fieldComments, + Map varInComments, + Map varOutComments, Map throwComments, Map errorComments, JavadocTaggable sigModel) { @@ -246,6 +255,33 @@ class MarkdownWriter { paramComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim())); else this.logger.warn("A @param for the {} bean and {} method is improperly formatted", logId); return; + case "field": + if (fieldComments == null) + break; + + matcher = this.namedCommentPattern.matcher(tagComment); + if (matcher.find()) + fieldComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim())); + else this.logger.warn("A @field for the {} bean and {} method is improperly formatted", logId); + return; + case "varIn": + if (varInComments == null) + break; + + matcher = this.namedCommentPattern.matcher(tagComment); + if (matcher.find()) + varInComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim())); + else this.logger.warn("A @field for the {} bean and {} method is improperly formatted", logId); + return; + case "varOut": + if (varOutComments == null) + break; + + matcher = this.namedCommentPattern.matcher(tagComment); + if (matcher.find()) + varOutComments.put(matcher.group(1), this.sanitize(matcher.group(2).trim())); + else this.logger.warn("A @field for the {} bean and {} method is improperly formatted", logId); + return; case "throws": if (throwComments == null) break; @@ -295,6 +331,45 @@ class MarkdownWriter { } } + private void buildMethodFields(ExecutableElement methodElement, String logId, + Map fieldComments, MethodSignatureFreemarkerModel sigModel) { + for (Entry fieldComment : fieldComments.entrySet()) { + this.logger.trace("Found BPMN field '{}' for '{}'", fieldComment.getKey(), logId); + + FieldFreemarkerModel fieldModel = new FieldFreemarkerModel(); + fieldModel.setName(fieldComment.getKey()); + fieldModel.setComment(fieldComment.getValue()); + + sigModel.getBpmnFields().put(fieldModel.getName(), fieldModel); + } + } + + private void buildMethodVariablesIn(ExecutableElement methodElement, String logId, + Map varComments, MethodSignatureFreemarkerModel sigModel) { + for (Entry varComment : varComments.entrySet()) { + this.logger.trace("Found input variable '{}' for '{}'", varComment.getKey(), logId); + + VarFreemarkerModel varModel = new VarFreemarkerModel(); + varModel.setName(varComment.getKey()); + varModel.setComment(varComment.getValue()); + + sigModel.getVariablesIn().put(varModel.getName(), varModel); + } + } + + private void buildMethodVariablesOut(ExecutableElement methodElement, String logId, + Map varComments, MethodSignatureFreemarkerModel sigModel) { + for (Entry varComment : varComments.entrySet()) { + this.logger.trace("Found output variable '{}' for '{}'", varComment.getKey(), logId); + + VarFreemarkerModel varModel = new VarFreemarkerModel(); + varModel.setName(varComment.getKey()); + varModel.setComment(varComment.getValue()); + + sigModel.getVariablesIn().put(varModel.getName(), varModel); + } + } + private void buildMethodThrows(ExecutableElement methodElement, String logId, Map throwComments, boolean hasBpmnErrorComments, MethodSignatureFreemarkerModel sigModel) { for (TypeMirror thrownType : methodElement.getThrownTypes()) { diff --git a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java index df6e454..3c7cdf8 100644 --- a/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java +++ b/src/main/java/com/inteligr8/activiti/doclet/MethodSignatureFreemarkerModel.java @@ -24,6 +24,12 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java private String methodSignature; private Map params = new LinkedHashMap<>(); + + private Map bpmnFields = new LinkedHashMap<>(); + + private Map variablesIn = new LinkedHashMap<>(); + + private Map variablesOut = new LinkedHashMap<>(); private String returnType; @@ -54,6 +60,30 @@ public class MethodSignatureFreemarkerModel implements JavadocDocumentable, Java public void setParams(Map params) { this.params = params; } + + public Map getBpmnFields() { + return bpmnFields; + } + + public void setBpmnFields(Map fields) { + this.bpmnFields = fields; + } + + public Map getVariablesIn() { + return variablesIn; + } + + public void setVariablesIn(Map variablesIn) { + this.variablesIn = variablesIn; + } + + public Map getVariablesOut() { + return variablesOut; + } + + public void setVariablesOut(Map variablesOut) { + this.variablesOut = variablesOut; + } public String getReturnType() { return returnType; diff --git a/src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java b/src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java new file mode 100644 index 0000000..5195b15 --- /dev/null +++ b/src/main/java/com/inteligr8/activiti/doclet/VarFreemarkerModel.java @@ -0,0 +1,42 @@ +/* + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or (at your + * option) any later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along + * with this program. If not, see . + */ +package com.inteligr8.activiti.doclet; + +/** + * @author brian@inteligr8.com + */ +public class VarFreemarkerModel { + + private String name; + + private String comment; + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getComment() { + return comment; + } + + public void setComment(String comment) { + this.comment = comment; + } + +} diff --git a/src/main/resources/templates/bean.md.ftl b/src/main/resources/templates/bean.md.ftl index ee32076..d247e02 100644 --- a/src/main/resources/templates/bean.md.ftl +++ b/src/main/resources/templates/bean.md.ftl @@ -80,27 +80,42 @@ This bean and its methods may be used in any "Expression" field or script in a S <#if sig.docBody??>${sig.docBody}<#else>No documentation available. <#if (sig.params?size > 0)> -| Parameter Name | Java Type | Documentation | -| ------------------------ | ------------------------------------------------ | ------------------------ | +| Input Type | Name | Java Type | Documentation | +| ------------------------ | ------------------------ | ------------------------------------------------ | ---------------------------------- | <#list sig.params as paramName, param> -| ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if (param.comment?? && param.comment?length > 0)>${param.comment?right_pad(24)}<#else>No documentation available. | +| Method Parameter | ${("`" + paramName + "`")?right_pad(24)} | ${("`" + param.type + "`")?right_pad(48)} | <#if (param.comment?? && param.comment?length > 0)>${param.comment?right_pad(32)}<#else>No documentation available. | +<#if (sig.bpmnFields?size > 0)> +<#list sig.bpmnFields as fieldName, field> +| BPMN Field | ${("`" + fieldName + "`")?right_pad(48)} | ${("")?right_pad(48)} | <#if (field.comment?? && field.comment?length > 0)>${field.comment?right_pad(32)}<#else>No documentation available. | + + +<#if (sig.variablesIn?size > 0)> +<#list sig.variablesIn as varName, var> +| Variable | ${("`" + varName + "`")?right_pad(48)} | ${("")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available. | + + <#if (sig.returnType?? || sig.throwTypes?size > 0)> -| Result Type | Java Type or BPMN Error Code | Documentation | -| ------------------------ | ------------------------------------------------ | ------------------------ | +| Result Type | Java Type, Name, or Error Code | Documentation | +| ------------------------ | ------------------------------------------------ | -------------------------------- | <#if sig.returnType??> -| Return Value | ${("`" + sig.returnType + "`")?right_pad(48)} | <#if (sig.tags.return?? && sig.tags.return[0]?length > 0)>${sig.tags.return[0]?right_pad(24)}<#else>No documentation available. | +| Return Value | ${("`" + sig.returnType + "`")?right_pad(48)} | <#if (sig.tags.return?? && sig.tags.return[0]?length > 0)>${sig.tags.return[0]?right_pad(32)}<#else>No documentation available. | + +<#if (sig.variablesOut?size > 0)> +<#list sig.variablesOut as varName, var> +| Variable | ${("`" + varName + "`")?right_pad(48)} | <#if (var.comment?? && var.comment?length > 0)>${var.comment?right_pad(32)}<#else>No documentation available. | + <#if (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. | +| Thrown Exception | ${("`" + throwType + "`")?right_pad(48)} | <#if (throw.comment?? && throw.comment?length > 0)>${throw.comment?right_pad(32)}<#else>No documentation available. | <#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. | +| Thrown BPMN Error | ${("`" + errorCode + "`")?right_pad(48)} | <#if (bpmnError.comment?? && bpmnError.comment?length > 0)>${bpmnError.comment?right_pad(32)}<#else>No documentation available. |