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.checks.javadoc;
021
022import java.util.Set;
023
024import com.puppycrawl.tools.checkstyle.StatelessCheck;
025import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
026import com.puppycrawl.tools.checkstyle.api.DetailAST;
027import com.puppycrawl.tools.checkstyle.api.FileContents;
028import com.puppycrawl.tools.checkstyle.api.Scope;
029import com.puppycrawl.tools.checkstyle.api.TextBlock;
030import com.puppycrawl.tools.checkstyle.api.TokenTypes;
031import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil;
032import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
033import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;
034
035/**
036 * <div>
037 * Checks for missing Javadoc comments for class, enum, interface, and annotation interface
038 * definitions. The scope to verify is specified using the {@code Scope} class and defaults
039 * to {@code Scope.PUBLIC}. To verify another scope, set property scope to one of the
040 * {@code Scope} constants.
041 * </div>
042 *
043 * @since 8.20
044 */
045@StatelessCheck
046public class MissingJavadocTypeCheck extends AbstractCheck {
047
048    /**
049     * A key is pointing to the warning message text in "messages.properties"
050     * file.
051     */
052    public static final String MSG_JAVADOC_MISSING = "javadoc.missing";
053
054    /** Specify the visibility scope where Javadoc comments are checked. */
055    private Scope scope = Scope.PUBLIC;
056    /** Specify the visibility scope where Javadoc comments are not checked. */
057    private Scope excludeScope;
058
059    /**
060     * Specify annotations that allow missed documentation.
061     * If annotation is present in target sources in multiple forms of qualified
062     * name, all forms should be listed in this property.
063     */
064    private Set<String> skipAnnotations = Set.of("Generated");
065
066    /**
067     * Setter to specify the visibility scope where Javadoc comments are checked.
068     *
069     * @param scope a scope.
070     * @since 8.20
071     */
072    public void setScope(Scope scope) {
073        this.scope = scope;
074    }
075
076    /**
077     * Setter to specify the visibility scope where Javadoc comments are not checked.
078     *
079     * @param excludeScope a scope.
080     * @since 8.20
081     */
082    public void setExcludeScope(Scope excludeScope) {
083        this.excludeScope = excludeScope;
084    }
085
086    /**
087     * Setter to specify annotations that allow missed documentation.
088     * If annotation is present in target sources in multiple forms of qualified
089     * name, all forms should be listed in this property.
090     *
091     * @param userAnnotations user's value.
092     * @since 8.20
093     */
094    public void setSkipAnnotations(String... userAnnotations) {
095        skipAnnotations = Set.of(userAnnotations);
096    }
097
098    @Override
099    public int[] getDefaultTokens() {
100        return getAcceptableTokens();
101    }
102
103    @Override
104    public int[] getAcceptableTokens() {
105        return new int[] {
106            TokenTypes.INTERFACE_DEF,
107            TokenTypes.CLASS_DEF,
108            TokenTypes.ENUM_DEF,
109            TokenTypes.ANNOTATION_DEF,
110            TokenTypes.RECORD_DEF,
111        };
112    }
113
114    @Override
115    public int[] getRequiredTokens() {
116        return CommonUtil.EMPTY_INT_ARRAY;
117    }
118
119    // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166
120    @Override
121    @SuppressWarnings("deprecation")
122    public void visitToken(DetailAST ast) {
123        if (shouldCheck(ast)) {
124            final FileContents contents = getFileContents();
125            final int lineNo = ast.getLineNo();
126            final TextBlock textBlock = contents.getJavadocBefore(lineNo);
127            if (textBlock == null) {
128                log(ast, MSG_JAVADOC_MISSING);
129            }
130        }
131    }
132
133    /**
134     * Whether we should check this node.
135     *
136     * @param ast a given node.
137     * @return whether we should check a given node.
138     */
139    private boolean shouldCheck(final DetailAST ast) {
140        final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast);
141
142        return surroundingScope.isIn(scope)
143                && (excludeScope == null || !surroundingScope.isIn(excludeScope))
144                && !AnnotationUtil.containsAnnotation(ast, skipAnnotations);
145    }
146
147}