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 com.puppycrawl.tools.checkstyle.StatelessCheck; 023import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 024import com.puppycrawl.tools.checkstyle.api.DetailAST; 025import com.puppycrawl.tools.checkstyle.api.TokenTypes; 026import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 027 028/** 029 * <p> 030 * Checks that Javadocs are located at the correct position. As specified at 031 * <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html"> 032 * Documentation Comment Specification for the Standard Doclet</a>, Javadocs are recognized 033 * only when placed immediately before module, package, class, interface, 034 * constructor, method, or field declarations. Any other position, like in the 035 * body of a method, will be ignored by the javadoc tool and is considered 036 * invalid by this check. 037 * </p> 038 * <p> 039 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 040 * </p> 041 * <p> 042 * Violation Message Keys: 043 * </p> 044 * <ul> 045 * <li> 046 * {@code invalid.position} 047 * </li> 048 * </ul> 049 * 050 * @since 8.23 051 */ 052@StatelessCheck 053public class InvalidJavadocPositionCheck extends AbstractCheck { 054 055 /** 056 * A key is pointing to the warning message text in "messages.properties" 057 * file. 058 */ 059 public static final String MSG_KEY = "invalid.position"; 060 061 @Override 062 public int[] getDefaultTokens() { 063 return new int[] { 064 TokenTypes.BLOCK_COMMENT_BEGIN, 065 }; 066 } 067 068 @Override 069 public int[] getAcceptableTokens() { 070 return getDefaultTokens(); 071 } 072 073 @Override 074 public int[] getRequiredTokens() { 075 return getDefaultTokens(); 076 } 077 078 @Override 079 public boolean isCommentNodesRequired() { 080 return true; 081 } 082 083 @Override 084 public void visitToken(DetailAST ast) { 085 final String commentContent = JavadocUtil.getBlockCommentContent(ast); 086 087 if (JavadocUtil.isJavadocComment(commentContent) 088 && !JavadocUtil.isCorrectJavadocPosition(ast)) { 089 log(ast, MSG_KEY); 090 } 091 } 092 093}