-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
36 changed files
with
1,199 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
232 changes: 232 additions & 0 deletions
232
...java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocLeadingAsteriskAlignCheck.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,232 @@ | ||
| /////////////////////////////////////////////////////////////////////////////////////////////// | ||
| // checkstyle: Checks Java source code and other text files for adherence to a set of rules. | ||
| // Copyright (C) 2001-2024 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.checks.javadoc; | ||
|
|
||
| import java.util.Arrays; | ||
| import java.util.List; | ||
| import java.util.regex.Matcher; | ||
| import java.util.regex.Pattern; | ||
|
|
||
| import com.puppycrawl.tools.checkstyle.GlobalStatefulCheck; | ||
| import com.puppycrawl.tools.checkstyle.api.DetailAST; | ||
| import com.puppycrawl.tools.checkstyle.api.DetailNode; | ||
| import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; | ||
| import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; | ||
|
|
||
| /** | ||
| * <p> | ||
| * Checks that the | ||
| * <a href="https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html#leading-asterisks"> | ||
| * leading asterisks</a> are aligned vertically under the second asterisk ( * ) | ||
| * of opening Javadoc tag. The alignment of closing Javadoc tag is also checked. | ||
| * If the line does not contain leading asterisk then that line will be ignored. | ||
| * </p> | ||
| * <p> | ||
| * If you're using tabs then specify the the tab width in the | ||
| * <a href="https://checkstyle.org/config.html#tabWidth">tabWidth</a> property. | ||
| * The default value of {@code tabWidth} is 8. | ||
| * </p> | ||
| * <ul> | ||
| * <li> | ||
| * Property {@code violateExecutionOnNonTightHtml} - Control when to print violations if the | ||
| * Javadoc being examined by this check violates the tight html rules defined at | ||
| * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>. | ||
| * Type is {@code boolean}. | ||
| * Default value is {@code false}. | ||
| * </li> | ||
| * </ul> | ||
| * <p> | ||
| * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} | ||
| * </p> | ||
| * <p> | ||
| * Violation Message Keys: | ||
| * </p> | ||
| * <ul> | ||
| * <li> | ||
| * {@code javadoc.asterisk.indentation} | ||
| * </li> | ||
| * <li> | ||
| * {@code javadoc.missed.html.close} | ||
| * </li> | ||
| * <li> | ||
| * {@code javadoc.parse.rule.error} | ||
| * </li> | ||
| * <li> | ||
| * {@code javadoc.unclosedHtml} | ||
| * </li> | ||
| * <li> | ||
| * {@code javadoc.wrong.singleton.html.tag} | ||
| * </li> | ||
| * </ul> | ||
| * | ||
| * @since 10.16.0 | ||
| */ | ||
| @GlobalStatefulCheck | ||
| public class JavadocLeadingAsteriskAlignCheck extends AbstractJavadocCheck { | ||
|
|
||
| /** | ||
| * A key is pointing to the warning message text in "messages.properties" | ||
| * file. | ||
| */ | ||
| public static final String MSG_KEY = "javadoc.asterisk.indentation"; | ||
|
|
||
| /** Specifies the tab. */ | ||
| private static final Pattern TAB = Pattern.compile("\t"); | ||
|
|
||
| /** Specifies the whitespace. */ | ||
| private static final String SPACE = " "; | ||
|
|
||
| /** Specifies the column number of starting block of the javadoc comment. */ | ||
| private int parentColNumber; | ||
| /** Specifies the line number of starting block of the javadoc comment. */ | ||
| private int parentLineNumber; | ||
|
|
||
| @Override | ||
| public int[] getDefaultJavadocTokens() { | ||
| return new int[] { | ||
| JavadocTokenTypes.LEADING_ASTERISK, | ||
| }; | ||
| } | ||
|
|
||
| @Override | ||
| public int[] getRequiredJavadocTokens() { | ||
| return getAcceptableJavadocTokens(); | ||
| } | ||
|
|
||
| // get the starting block of javadoc | ||
| @Override | ||
| public void beginJavadocTree(DetailNode rootAst) { | ||
| final String startLine = getLines()[rootAst.getLineNumber() - 1]; | ||
| parentColNumber = getColumnForStartToken(startLine); | ||
| parentLineNumber = rootAst.getLineNumber(); | ||
| } | ||
|
|
||
| // process leading asterisks of the javadoc | ||
| @Override | ||
| public void visitJavadocToken(DetailNode ast) { | ||
| if (ast.getLineNumber() != parentLineNumber) { | ||
| final int commentIndex = getColumnForCommentText(ast.getText()); | ||
|
|
||
| checkAsteriskAlignment( | ||
| ast.getLineNumber(), | ||
| parentColNumber, | ||
| commentIndex); | ||
| } | ||
| } | ||
|
|
||
| // process the end block of javadoc | ||
| @Override | ||
| public void finishJavadocTree(DetailNode rootAst) { | ||
| final DetailAST javadocEndToken = getBlockCommentAst().getLastChild(); | ||
|
|
||
| if (parentLineNumber != javadocEndToken.getLineNo()) { | ||
| final String lastLine = getLastLine(javadocEndToken); | ||
| final int commentIndex = getColumnForCommentText(lastLine); | ||
|
|
||
| checkAsteriskAlignment( | ||
| javadocEndToken.getLineNo(), | ||
| parentColNumber, | ||
| commentIndex); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Processes and sets the last line of javadoc which includes comment's ending token. | ||
| * | ||
| * @param endToken javadoc ending token | ||
| * @return last line of javadoc comment including ending token | ||
| */ | ||
| private String getLastLine(DetailAST endToken) { | ||
| final String lastLine; | ||
|
|
||
| if (endToken.getColumnNo() == 0) { | ||
| lastLine = endToken.getText(); | ||
| } | ||
| else { | ||
| final String blockComment = JavadocUtil.getBlockCommentContent(getBlockCommentAst()); | ||
| final List<String> commentTextLineList = Arrays.asList(blockComment.split("\n")); | ||
| lastLine = commentTextLineList.get(commentTextLineList.size() - 1) + "*/"; | ||
| } | ||
|
|
||
| return lastLine; | ||
| } | ||
|
|
||
| /** | ||
| * Processes and returns the column number of leading asterisk from javadoc comment text. | ||
| * | ||
| * @param line single line from block comment text | ||
| * @return column number of asterisk | ||
| */ | ||
| private int getColumnForCommentText(String line) { | ||
| final Matcher tabMatcher = TAB.matcher(line); | ||
| final String lineWithoutTabs = tabMatcher.replaceAll(SPACE.repeat(getTabWidth())); | ||
| final Pattern pattern = Pattern.compile("^(\\s*)\\*"); | ||
| final Matcher matcher = pattern.matcher(lineWithoutTabs); | ||
| final int columnNumber; | ||
|
|
||
| if (matcher.find()) { | ||
| columnNumber = matcher.group(1).length() + 1; | ||
| } | ||
| else { | ||
| columnNumber = -1; | ||
| } | ||
|
|
||
| return columnNumber; | ||
| } | ||
|
|
||
| /** | ||
| * Processes and returns the column number of starting block of javadoc comment. | ||
| * | ||
| * @param line starting line of the javadoc comment | ||
| * @return column number of start token | ||
| * @noinspection ResultOfMethodCallIgnored | ||
| * @noinspectionreason ResultOfMethodCallIgnored- the file cannot be read without calling | ||
| * the find() method. In our case we are sure that the find() will always be true, so | ||
| * we don't need to check its result | ||
| */ | ||
| private int getColumnForStartToken(String line) { | ||
| final Matcher tabMatcher = TAB.matcher(line); | ||
| final String lineWithoutTabs = tabMatcher.replaceAll(SPACE.repeat(getTabWidth())); | ||
| final Pattern pattern = Pattern.compile("^(.*)/\\*\\*"); | ||
| final Matcher matcher = pattern.matcher(lineWithoutTabs); | ||
| matcher.find(); | ||
|
|
||
| return matcher.group(1).length() + 2; | ||
| } | ||
|
|
||
| /** | ||
| * Checks alignment of asterisks and logs violations. | ||
| * | ||
| * @param lineNumber line number of current comment line | ||
| * @param commentBeginColumn column number of javadoc starting token | ||
| * @param asteriskColumn column number of current line's leading asterisk | ||
| */ | ||
| private void checkAsteriskAlignment(int lineNumber, | ||
| int commentBeginColumn, | ||
| int asteriskColumn) { | ||
|
|
||
| if (asteriskColumn != -1) { | ||
| final int columnDifference = commentBeginColumn - asteriskColumn; | ||
| if (columnDifference != 0) { | ||
| log(lineNumber, asteriskColumn - 1, MSG_KEY, commentBeginColumn); | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.