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