ModuleJavadocParsingUtil.java
///////////////////////////////////////////////////////////////////////////////////////////////
// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
// Copyright (C) 2001-2025 the original author or authors.
//
// This library 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 2.1 of the License, or (at your option) any later version.
//
// This library 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
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
///////////////////////////////////////////////////////////////////////////////////////////////
package com.puppycrawl.tools.checkstyle.site;
import java.util.Optional;
import java.util.Set;
import java.util.regex.Pattern;
import org.apache.maven.doxia.macro.MacroExecutionException;
import org.apache.maven.doxia.sink.Sink;
import com.puppycrawl.tools.checkstyle.api.DetailNode;
import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
import com.puppycrawl.tools.checkstyle.meta.JavadocMetadataScraper;
import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
/**
* Utility class for parsing javadocs of modules.
*/
public final class ModuleJavadocParsingUtil {
/** New line escape character. */
public static final String NEWLINE = System.lineSeparator();
/** A newline with 8 spaces of indentation. */
public static final String INDENT_LEVEL_8 = SiteUtil.getNewlineAndIndentSpaces(8);
/** A newline with 10 spaces of indentation. */
public static final String INDENT_LEVEL_10 = SiteUtil.getNewlineAndIndentSpaces(10);
/** A newline with 12 spaces of indentation. */
public static final String INDENT_LEVEL_12 = SiteUtil.getNewlineAndIndentSpaces(12);
/** A newline with 14 spaces of indentation. */
public static final String INDENT_LEVEL_14 = SiteUtil.getNewlineAndIndentSpaces(14);
/** A newline with 16 spaces of indentation. */
public static final String INDENT_LEVEL_16 = SiteUtil.getNewlineAndIndentSpaces(16);
/** A newline with 18 spaces of indentation. */
public static final String INDENT_LEVEL_18 = SiteUtil.getNewlineAndIndentSpaces(18);
/** A newline with 20 spaces of indentation. */
public static final String INDENT_LEVEL_20 = SiteUtil.getNewlineAndIndentSpaces(20);
/** A set of all html tags that need to be considered as text formatting for this macro. */
public 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>");
/** "Notes:" javadoc marking. */
public static final String NOTES = "Notes:";
/** "Notes:" line. */
public static final Pattern NOTES_LINE = Pattern.compile("\\s*" + NOTES + "$");
/**
* Private utility constructor.
*/
private ModuleJavadocParsingUtil() {
}
/**
* Gets properties of the specified module.
*
* @param moduleName name of module.
* @return set of properties name if present, otherwise null.
* @throws MacroExecutionException if the module could not be retrieved.
*/
public static Set<String> getPropertyNames(String moduleName)
throws MacroExecutionException {
final Object instance = SiteUtil.getModuleInstance(moduleName);
final Class<?> clss = instance.getClass();
return SiteUtil.getPropertiesForDocumentation(clss, instance);
}
/**
* Gets the starting index of the "Parent is" paragraph in module's javadoc.
*
* @param moduleJavadoc javadoc of module.
* @return start index of parent subsection.
*/
public static int getParentSectionStartIndex(DetailNode moduleJavadoc) {
int parentStartIndex = -1;
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;
}
/**
* Gets the start index of the Notes section.
*
* @param moduleJavadoc javadoc of module.
* @return start index.
*/
public static int getNotesSectionStartIndex(DetailNode moduleJavadoc) {
int notesStartIndex = -1;
for (DetailNode node : moduleJavadoc.getChildren()) {
if (node.getType() == JavadocTokenTypes.HTML_ELEMENT
&& isStartOfNotesSection(node)) {
notesStartIndex += node.getIndex();
break;
}
}
return notesStartIndex;
}
/**
* Determines whether the given HTML node marks the start of the "Notes" section.
*
* @param htmlElement html element to check.
* @return true if the element starts the "Notes" section, false otherwise.
*/
private static boolean isStartOfNotesSection(DetailNode htmlElement) {
final DetailNode paragraphNode = JavadocUtil.findFirstToken(
htmlElement, JavadocTokenTypes.PARAGRAPH);
final Optional<DetailNode> liNode = getLiTagNode(htmlElement);
return paragraphNode != null && JavadocMetadataScraper.isChildNodeTextMatches(
paragraphNode, NOTES_LINE)
|| liNode.isPresent() && JavadocMetadataScraper.isChildNodeTextMatches(
liNode.get(), NOTES_LINE);
}
/**
* Gets the node of Li HTML tag.
*
* @param htmlElement html element to get li tag from.
* @return Optional of li tag node.
*/
public static Optional<DetailNode> getLiTagNode(DetailNode htmlElement) {
return Optional.of(htmlElement)
.map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.HTML_TAG))
.map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.HTML_ELEMENT))
.map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.LI));
}
/**
* Gets the start index of property section in module's javadoc.
*
* @param moduleJavadoc javadoc of module.
* @param propertyNames set with property names.
* @return index of property section.
*/
public static int getPropertySectionStartIndex(DetailNode moduleJavadoc,
Set<String> propertyNames) {
int propertySectionStartIndex = -1;
final String somePropertyName = propertyNames.iterator().next();
final Optional<DetailNode> somePropertyModuleNode =
SiteUtil.getPropertyJavadocNodeInModule(somePropertyName, moduleJavadoc);
if (somePropertyModuleNode.isPresent()) {
propertySectionStartIndex = JavadocMetadataScraper.getParentIndexOf(
somePropertyModuleNode.get());
}
return propertySectionStartIndex;
}
/**
* Writes the given javadoc chunk into xdoc.
*
* @param javadocPortion javadoc text.
* @param sink sink of the macro.
*/
public static void writeOutJavadocPortion(String javadocPortion, Sink sink) {
final String[] javadocPortionLinesSplit = javadocPortion.split(NEWLINE
.replace("\r", ""));
sink.rawText(javadocPortionLinesSplit[0]);
String lastHtmlTag = javadocPortionLinesSplit[0];
for (int index = 1; index < javadocPortionLinesSplit.length; index++) {
final String currentLine = javadocPortionLinesSplit[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 = javadocPortionLinesSplit[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.
*/
public static boolean startsWithTextFormattingHtmlTag(String line) {
boolean result = false;
for (String tag : HTML_TEXT_FORMAT_TAGS) {
if (line.startsWith(tag)) {
result = true;
break;
}
}
return result;
}
}