The Description and Notes macros that I created significantly repeat in functionality as I've copied and used many methods from the prior for the latter.
References to methods in DescriptionMacro that are repeatedly being used in upcoming NotesMacro:
|
/** |
|
* Assigns values to each instance variable. |
|
* |
|
* @param moduleName name of module. |
|
* @return set of property names. |
|
* @throws MacroExecutionException if the module could not be retrieved. |
|
*/ |
|
private static Set<String> getPropertyNames(String moduleName) |
|
throws MacroExecutionException { |
|
final Object instance = SiteUtil.getModuleInstance(moduleName); |
|
final Class<?> clss = instance.getClass(); |
|
|
|
return SiteUtil.getPropertiesForDocumentation(clss, instance); |
|
} |
Note: this method below might just become similar, but not the same, in the future due to potentially adding additional conditional statement that checks for notes section in javadoc
|
/** |
|
* Gets the end index of the description. |
|
* |
|
* @param moduleJavadoc javadoc of module. |
|
* @param propertyNamesSet Set with property names. |
|
* @return the end index. |
|
*/ |
|
private static int getDescriptionEndIndex(DetailNode moduleJavadoc, |
|
Set<String> propertyNamesSet) { |
|
int descriptionEndIndex = -1; |
|
|
|
if (propertyNamesSet.isEmpty()) { |
|
descriptionEndIndex += getParentSectionStartIndex(moduleJavadoc); |
|
} |
|
else { |
|
final String somePropertyName = propertyNamesSet.iterator().next(); |
|
|
|
final Optional<DetailNode> somePropertyModuleNode = |
|
SiteUtil.getPropertyJavadocNodeInModule( |
|
somePropertyName, moduleJavadoc); |
|
|
|
if (somePropertyModuleNode.isPresent()) { |
|
descriptionEndIndex += JavadocMetadataScraper |
|
.getParentIndexOf(somePropertyModuleNode.get()); |
|
} |
|
} |
|
|
|
return descriptionEndIndex; |
|
} |
|
/** |
|
* Gets the starting index of the "Parent is" paragraph in module's javadoc. |
|
* |
|
* @param moduleJavadoc javadoc of module. |
|
* @return start index of parent subsection. |
|
*/ |
|
private static int getParentSectionStartIndex(DetailNode moduleJavadoc) { |
|
int parentStartIndex = 0; |
|
|
|
for (DetailNode node : moduleJavadoc.getChildren()) { |
|
if (node.getType() == JavadocTokenTypes.HTML_ELEMENT) { |
|
final DetailNode paragraphNode = JavadocUtil.findFirstToken( |
|
node, JavadocTokenTypes.PARAGRAPH); |
|
if (paragraphNode != null && JavadocMetadataScraper.isParentText(paragraphNode)) { |
|
parentStartIndex = node.getIndex(); |
|
break; |
|
} |
|
} |
|
} |
|
|
|
return parentStartIndex; |
|
} |
|
/** |
|
* Writes the description into xdoc. |
|
* |
|
* @param description description of the module. |
|
* @param sink sink of the macro. |
|
*/ |
|
private static void writeOutDescription(String description, Sink sink) { |
|
final String[] moduleDescriptionLinesSplit = description.split(NEWLINE); |
|
|
|
sink.rawText(moduleDescriptionLinesSplit[0]); |
|
String lastHtmlTag = moduleDescriptionLinesSplit[0]; |
|
|
|
for (int index = 1; index < moduleDescriptionLinesSplit.length; index++) { |
|
final String currentLine = moduleDescriptionLinesSplit[index].trim(); |
|
final String processedLine; |
|
|
|
if (currentLine.isEmpty()) { |
|
processedLine = NEWLINE; |
|
} |
|
else if (currentLine.startsWith("<") |
|
&& !startsWithTextFormattingHtmlTag(currentLine)) { |
|
|
|
processedLine = INDENT_LEVEL_8 + currentLine; |
|
lastHtmlTag = currentLine; |
|
} |
|
else if (lastHtmlTag.contains("<pre")) { |
|
final String currentLineWithPreservedIndent = moduleDescriptionLinesSplit[index] |
|
.substring(1); |
|
|
|
processedLine = NEWLINE + currentLineWithPreservedIndent; |
|
} |
|
else { |
|
processedLine = INDENT_LEVEL_10 + currentLine; |
|
} |
|
|
|
sink.rawText(processedLine); |
|
} |
|
|
|
} |
|
/** |
|
* Checks if given line starts with HTML text-formatting tag. |
|
* |
|
* @param line line to check on. |
|
* @return whether given line starts with HTML text-formatting tag. |
|
*/ |
|
private static boolean startsWithTextFormattingHtmlTag(String line) { |
|
boolean result = false; |
|
|
|
for (String tag : HTML_TEXT_FORMAT_TAGS) { |
|
if (line.startsWith(tag)) { |
|
result = true; |
|
break; |
|
} |
|
} |
|
|
|
return result; |
|
} |
|
|
|
} |
and the following constant variables:
|
/** New line escape character. */ |
|
private static final String NEWLINE = "\n"; |
|
/** A newline with 8 spaces of indentation. */ |
|
private static final String INDENT_LEVEL_8 = SiteUtil.getNewlineAndIndentSpaces(8); |
|
/** A newline with 10 spaces of indentation. */ |
|
private static final String INDENT_LEVEL_10 = SiteUtil.getNewlineAndIndentSpaces(10); |
|
/** A set of all html tags that need to be considered as text formatting for this macro. */ |
|
private static final Set<String> HTML_TEXT_FORMAT_TAGS = Set.of("<code>", "<a", "</a>", "<b>", |
|
"</b>", "<strong>", "</strong>", "<i>", "</i>", "<em>", "</em>", "<small>", "</small>", |
|
"<ins>", "<sub>", "<sup>"); |
Thus, we should create new Utility class that could store those members for both Macros to use.
Besides, perhaps other macros also have repeating implementation which we could add in that new utility class.
The Description and Notes macros that I created significantly repeat in functionality as I've copied and used many methods from the prior for the latter.
References to methods in DescriptionMacro that are repeatedly being used in upcoming NotesMacro:
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 77 to 90 in 77aafae
Note: this method below might just become similar, but not the same, in the future due to potentially adding additional conditional statement that checks for notes section in javadoc
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 92 to 120 in 77aafae
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 122 to 143 in 77aafae
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 145 to 183 in 77aafae
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 185 to 204 in 77aafae
and the following constant variables:
checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/site/DescriptionMacro.java
Lines 47 to 56 in 77aafae
Thus, we should create new Utility class that could store those members for both Macros to use.
Besides, perhaps other macros also have repeating implementation which we could add in that new utility class.