001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2020 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.checks.javadoc; 021 022import java.util.ArrayList; 023import java.util.Arrays; 024import java.util.List; 025import java.util.stream.Collectors; 026 027import com.puppycrawl.tools.checkstyle.StatelessCheck; 028import com.puppycrawl.tools.checkstyle.api.DetailAST; 029import com.puppycrawl.tools.checkstyle.api.DetailNode; 030import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 031import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 032import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 033 034/** 035 * <p> 036 * Checks that a Javadoc block can fit in a single line and doesn't contain at-clauses. 037 * Javadoc comment that contains at least one at-clause should be formatted in a few lines. 038 * </p> 039 * <ul> 040 * <li> 041 * Property {@code violateExecutionOnNonTightHtml} - Control when to print violations 042 * if the Javadoc being examined by this check violates the tight html rules defined at 043 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>. 044 * Type is {@code boolean}. 045 * Default value is {@code false}. 046 * </li> 047 * <li> 048 * Property {@code ignoredTags} - Specify at-clauses which are ignored by the check. 049 * Type is {@code java.lang.String[]}. 050 * Default value is {@code {}}. 051 * </li> 052 * <li> 053 * Property {@code ignoreInlineTags} - Control whether inline tags must be ignored. 054 * Type is {@code boolean}. 055 * Default value is {@code true}. 056 * </li> 057 * </ul> 058 * <p> 059 * To configure the check: 060 * </p> 061 * <pre> 062 * <module name="SingleLineJavadoc"/> 063 * </pre> 064 * <p> 065 * To configure the check with a list of ignored at-clauses 066 * and make inline at-clauses not ignored: 067 * </p> 068 * <pre> 069 * <module name="SingleLineJavadoc"> 070 * <property name="ignoredTags" value="@inheritDoc, @see"/> 071 * <property name="ignoreInlineTags" value="false"/> 072 * </module> 073 * </pre> 074 * <p> 075 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 076 * </p> 077 * <p> 078 * Violation Message Keys: 079 * </p> 080 * <ul> 081 * <li> 082 * {@code javadoc.missed.html.close} 083 * </li> 084 * <li> 085 * {@code javadoc.parse.rule.error} 086 * </li> 087 * <li> 088 * {@code javadoc.wrong.singleton.html.tag} 089 * </li> 090 * <li> 091 * {@code singleline.javadoc} 092 * </li> 093 * </ul> 094 * 095 * @since 6.0 096 */ 097@StatelessCheck 098public class SingleLineJavadocCheck extends AbstractJavadocCheck { 099 100 /** 101 * A key is pointing to the warning message text in "messages.properties" 102 * file. 103 */ 104 public static final String MSG_KEY = "singleline.javadoc"; 105 106 /** 107 * Specify at-clauses which are ignored by the check. 108 */ 109 private List<String> ignoredTags = new ArrayList<>(); 110 111 /** Control whether inline tags must be ignored. */ 112 private boolean ignoreInlineTags = true; 113 114 /** 115 * Setter to specify at-clauses which are ignored by the check. 116 * 117 * @param tags to be ignored by check. 118 */ 119 public void setIgnoredTags(String... tags) { 120 ignoredTags = Arrays.stream(tags).collect(Collectors.toList()); 121 } 122 123 /** 124 * Setter to control whether inline tags must be ignored. 125 * 126 * @param ignoreInlineTags whether inline tags must be ignored. 127 */ 128 public void setIgnoreInlineTags(boolean ignoreInlineTags) { 129 this.ignoreInlineTags = ignoreInlineTags; 130 } 131 132 @Override 133 public int[] getDefaultJavadocTokens() { 134 return new int[] { 135 JavadocTokenTypes.JAVADOC, 136 }; 137 } 138 139 @Override 140 public int[] getRequiredJavadocTokens() { 141 return getAcceptableJavadocTokens(); 142 } 143 144 @Override 145 public void visitJavadocToken(DetailNode ast) { 146 if (isSingleLineJavadoc(getBlockCommentAst()) 147 && (hasJavadocTags(ast) || !ignoreInlineTags && hasJavadocInlineTags(ast))) { 148 log(ast.getLineNumber(), MSG_KEY); 149 } 150 } 151 152 /** 153 * Checks if comment is single line comment. 154 * 155 * @param blockCommentStart the AST tree in which a block comment starts 156 * @return true, if comment is single line comment. 157 */ 158 private static boolean isSingleLineJavadoc(DetailAST blockCommentStart) { 159 final DetailAST blockCommentEnd = blockCommentStart.getLastChild(); 160 return TokenUtil.areOnSameLine(blockCommentStart, blockCommentEnd); 161 } 162 163 /** 164 * Checks if comment has javadoc tags which are not ignored. Also works 165 * on custom tags. As block tags can be interpreted only at the beginning of a line, 166 * only the first instance is checked. 167 * 168 * @param javadocRoot javadoc root node. 169 * @return true, if comment has javadoc tags which are not ignored. 170 * @see <a href= 171 * "https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#blockandinlinetags"> 172 * Block and inline tags</a> 173 */ 174 private boolean hasJavadocTags(DetailNode javadocRoot) { 175 final DetailNode javadocTagSection = 176 JavadocUtil.findFirstToken(javadocRoot, JavadocTokenTypes.JAVADOC_TAG); 177 return javadocTagSection != null && !isTagIgnored(javadocTagSection); 178 } 179 180 /** 181 * Checks if comment has in-line tags which are not ignored. 182 * 183 * @param javadocRoot javadoc root node. 184 * @return true, if comment has in-line tags which are not ignored. 185 * @see <a href= 186 * "https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#javadoctags"> 187 * JavadocTags</a> 188 */ 189 private boolean hasJavadocInlineTags(DetailNode javadocRoot) { 190 DetailNode javadocTagSection = 191 JavadocUtil.findFirstToken(javadocRoot, JavadocTokenTypes.JAVADOC_INLINE_TAG); 192 boolean foundTag = false; 193 while (javadocTagSection != null) { 194 if (!isTagIgnored(javadocTagSection)) { 195 foundTag = true; 196 break; 197 } 198 javadocTagSection = JavadocUtil.getNextSibling( 199 javadocTagSection, JavadocTokenTypes.JAVADOC_INLINE_TAG); 200 } 201 return foundTag; 202 } 203 204 /** 205 * Checks if list of ignored tags contains javadocTagSection's javadoc tag. 206 * 207 * @param javadocTagSection to check javadoc tag in. 208 * @return true, if ignoredTags contains javadocTagSection's javadoc tag. 209 */ 210 private boolean isTagIgnored(DetailNode javadocTagSection) { 211 return ignoredTags.contains(JavadocUtil.getTagName(javadocTagSection)); 212 } 213 214}