Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.site;
021
022import java.util.Optional;
023import java.util.Set;
024import java.util.regex.Pattern;
025
026import org.apache.maven.doxia.macro.MacroExecutionException;
027import org.apache.maven.doxia.sink.Sink;
028
029import com.puppycrawl.tools.checkstyle.api.DetailNode;
030import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
031import com.puppycrawl.tools.checkstyle.meta.JavadocMetadataScraper;
032import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
033
034/**
035 * Utility class for parsing javadocs of modules.
036 */
037public final class ModuleJavadocParsingUtil {
038    /** New line escape character. */
039    public static final String NEWLINE = System.lineSeparator();
040    /** A newline with 8 spaces of indentation. */
041    public static final String INDENT_LEVEL_8 = SiteUtil.getNewlineAndIndentSpaces(8);
042    /** A newline with 10 spaces of indentation. */
043    public static final String INDENT_LEVEL_10 = SiteUtil.getNewlineAndIndentSpaces(10);
044    /** A newline with 12 spaces of indentation. */
045    public static final String INDENT_LEVEL_12 = SiteUtil.getNewlineAndIndentSpaces(12);
046    /** A newline with 14 spaces of indentation. */
047    public static final String INDENT_LEVEL_14 = SiteUtil.getNewlineAndIndentSpaces(14);
048    /** A newline with 16 spaces of indentation. */
049    public static final String INDENT_LEVEL_16 = SiteUtil.getNewlineAndIndentSpaces(16);
050    /** A newline with 18 spaces of indentation. */
051    public static final String INDENT_LEVEL_18 = SiteUtil.getNewlineAndIndentSpaces(18);
052    /** A newline with 20 spaces of indentation. */
053    public static final String INDENT_LEVEL_20 = SiteUtil.getNewlineAndIndentSpaces(20);
054    /** A set of all html tags that need to be considered as text formatting for this macro. */
055    public static final Set<String> HTML_TEXT_FORMAT_TAGS = Set.of("<code>", "<a", "</a>", "<b>",
056        "</b>", "<strong>", "</strong>", "<i>", "</i>", "<em>", "</em>", "<small>", "</small>",
057        "<ins>", "<sub>", "<sup>");
058    /** "Notes:" javadoc marking. */
059    public static final String NOTES = "Notes:";
060    /** "Notes:" line. */
061    public static final Pattern NOTES_LINE = Pattern.compile("\\s*" + NOTES + "$");
062
063    /**
064     * Private utility constructor.
065     */
066    private ModuleJavadocParsingUtil() {
067    }
068
069    /**
070     * Gets properties of the specified module.
071     *
072     * @param moduleName name of module.
073     * @return set of properties name if present, otherwise null.
074     * @throws MacroExecutionException if the module could not be retrieved.
075     */
076    public static Set<String> getPropertyNames(String moduleName)
077            throws MacroExecutionException {
078        final Object instance = SiteUtil.getModuleInstance(moduleName);
079        final Class<?> clss = instance.getClass();
080
081        return SiteUtil.getPropertiesForDocumentation(clss, instance);
082    }
083
084    /**
085     * Gets the starting index of the "Parent is" paragraph in module's javadoc.
086     *
087     * @param moduleJavadoc javadoc of module.
088     * @return start index of parent subsection.
089     */
090    public static int getParentSectionStartIndex(DetailNode moduleJavadoc) {
091        int parentStartIndex = -1;
092
093        for (DetailNode node : moduleJavadoc.getChildren()) {
094            if (node.getType() == JavadocTokenTypes.HTML_ELEMENT) {
095                final DetailNode paragraphNode = JavadocUtil.findFirstToken(
096                    node, JavadocTokenTypes.PARAGRAPH);
097                if (paragraphNode != null && JavadocMetadataScraper.isParentText(paragraphNode)) {
098                    parentStartIndex = node.getIndex();
099                    break;
100                }
101            }
102        }
103
104        return parentStartIndex;
105    }
106
107    /**
108     * Gets the start index of the Notes section.
109     *
110     * @param moduleJavadoc javadoc of module.
111     * @return start index.
112     */
113    public static int getNotesSectionStartIndex(DetailNode moduleJavadoc) {
114        int notesStartIndex = -1;
115
116        for (DetailNode node : moduleJavadoc.getChildren()) {
117            if (node.getType() == JavadocTokenTypes.HTML_ELEMENT
118                && isStartOfNotesSection(node)) {
119
120                notesStartIndex += node.getIndex();
121                break;
122            }
123        }
124
125        return notesStartIndex;
126    }
127
128    /**
129     * Determines whether the given HTML node marks the start of the "Notes" section.
130     *
131     * @param htmlElement html element to check.
132     * @return true if the element starts the "Notes" section, false otherwise.
133     */
134    private static boolean isStartOfNotesSection(DetailNode htmlElement) {
135        final DetailNode paragraphNode = JavadocUtil.findFirstToken(
136            htmlElement, JavadocTokenTypes.PARAGRAPH);
137        final Optional<DetailNode> liNode = getLiTagNode(htmlElement);
138
139        return paragraphNode != null && JavadocMetadataScraper.isChildNodeTextMatches(
140            paragraphNode, NOTES_LINE)
141            || liNode.isPresent() && JavadocMetadataScraper.isChildNodeTextMatches(
142                liNode.get(), NOTES_LINE);
143    }
144
145    /**
146     * Gets the node of Li HTML tag.
147     *
148     * @param htmlElement html element to get li tag from.
149     * @return Optional of li tag node.
150     */
151    public static Optional<DetailNode> getLiTagNode(DetailNode htmlElement) {
152        return Optional.of(htmlElement)
153            .map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.HTML_TAG))
154            .map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.HTML_ELEMENT))
155            .map(element -> JavadocUtil.findFirstToken(element, JavadocTokenTypes.LI));
156    }
157
158    /**
159     * Gets the start index of property section in module's javadoc.
160     *
161     * @param moduleJavadoc javadoc of module.
162     * @param propertyNames set with property names.
163     * @return index of property section.
164     */
165    public static int getPropertySectionStartIndex(DetailNode moduleJavadoc,
166                                                   Set<String> propertyNames) {
167        int propertySectionStartIndex = -1;
168
169        final String somePropertyName = propertyNames.iterator().next();
170        final Optional<DetailNode> somePropertyModuleNode =
171            SiteUtil.getPropertyJavadocNodeInModule(somePropertyName, moduleJavadoc);
172
173        if (somePropertyModuleNode.isPresent()) {
174            propertySectionStartIndex = JavadocMetadataScraper.getParentIndexOf(
175                somePropertyModuleNode.get());
176        }
177
178        return propertySectionStartIndex;
179    }
180
181    /**
182     * Writes the given javadoc chunk into xdoc.
183     *
184     * @param javadocPortion javadoc text.
185     * @param sink sink of the macro.
186     */
187    public static void writeOutJavadocPortion(String javadocPortion, Sink sink) {
188        final String[] javadocPortionLinesSplit = javadocPortion.split(NEWLINE
189            .replace("\r", ""));
190
191        sink.rawText(javadocPortionLinesSplit[0]);
192        String lastHtmlTag = javadocPortionLinesSplit[0];
193
194        for (int index = 1; index < javadocPortionLinesSplit.length; index++) {
195            final String currentLine = javadocPortionLinesSplit[index].trim();
196            final String processedLine;
197
198            if (currentLine.isEmpty()) {
199                processedLine = NEWLINE;
200            }
201            else if (currentLine.startsWith("<")
202                && !startsWithTextFormattingHtmlTag(currentLine)) {
203
204                processedLine = INDENT_LEVEL_8 + currentLine;
205                lastHtmlTag = currentLine;
206            }
207            else if (lastHtmlTag.contains("<pre")) {
208                final String currentLineWithPreservedIndent = javadocPortionLinesSplit[index]
209                    .substring(1);
210
211                processedLine = NEWLINE + currentLineWithPreservedIndent;
212            }
213            else {
214                processedLine = INDENT_LEVEL_10 + currentLine;
215            }
216
217            sink.rawText(processedLine);
218        }
219
220    }
221
222    /**
223     * Checks if given line starts with HTML text-formatting tag.
224     *
225     * @param line line to check on.
226     * @return whether given line starts with HTML text-formatting tag.
227     */
228    public static boolean startsWithTextFormattingHtmlTag(String line) {
229        boolean result = false;
230
231        for (String tag : HTML_TEXT_FORMAT_TAGS) {
232            if (line.startsWith(tag)) {
233                result = true;
234                break;
235            }
236        }
237
238        return result;
239    }
240
241}