Skip to content

Commit

Permalink
InvalidSnippet: flag snippets which seem to omit the ":" required for…
Browse files Browse the repository at this point in the history
… inline code.

PiperOrigin-RevId: 703495289
  • Loading branch information
graememorgan authored and Error Prone Team committed Dec 12, 2024
1 parent a26105b commit 673aca3
Show file tree
Hide file tree
Showing 3 changed files with 170 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
/*
* Copyright 2024 The Error Prone Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.errorprone.bugpatterns.javadoc;

import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;
import static com.google.errorprone.bugpatterns.javadoc.Utils.diagnosticPosition;

import com.google.errorprone.BugPattern;
import com.google.errorprone.VisitorState;
import com.google.errorprone.bugpatterns.BugChecker;
import com.google.errorprone.bugpatterns.BugChecker.ClassTreeMatcher;
import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;
import com.google.errorprone.bugpatterns.BugChecker.VariableTreeMatcher;
import com.google.errorprone.matchers.Description;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.ErroneousTree;
import com.sun.source.tree.ClassTree;
import com.sun.source.tree.MethodTree;
import com.sun.source.tree.VariableTree;
import com.sun.source.util.DocTreePath;
import com.sun.source.util.DocTreePathScanner;

/** A bug pattern; see the summary. */
@BugPattern(summary = "This tag is invalid.", severity = WARNING, documentSuppression = false)
public final class InvalidSnippet extends BugChecker
implements ClassTreeMatcher, MethodTreeMatcher, VariableTreeMatcher {

private void scanTags(VisitorState state, DocTreePath path) {
new InvalidTagChecker(state).scan(path, null);
}

@Override
public Description matchClass(ClassTree classTree, VisitorState state) {
DocTreePath path = Utils.getDocTreePath(state);
if (path != null) {
scanTags(state, path);
}
return Description.NO_MATCH;
}

@Override
public Description matchMethod(MethodTree methodTree, VisitorState state) {
DocTreePath path = Utils.getDocTreePath(state);
if (path != null) {
scanTags(state, path);
}
return Description.NO_MATCH;
}

@Override
public Description matchVariable(VariableTree variableTree, VisitorState state) {
DocTreePath path = Utils.getDocTreePath(state);
if (path != null) {
scanTags(state, path);
}
return Description.NO_MATCH;
}

final class InvalidTagChecker extends DocTreePathScanner<Void, Void> {
private final VisitorState state;

private InvalidTagChecker(VisitorState state) {
this.state = state;
}

@Override
public Void visitErroneous(ErroneousTree erroneousTree, Void unused) {
if (erroneousTree.getBody().startsWith("{@snippet")) {
String message =
"This @snippet tag looks to be malformed. Did you forget the \":\"? Snippets should"
+ " start with \"{@snippet :\" followed by a newline.";
state.reportMatch(
buildDescription(diagnosticPosition(getCurrentPath(), state))
.setMessage(message)
.build());
}
return null;
}

@Override
public Void scan(DocTree tree, Void unused) {
return super.scan(tree, null);
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,7 @@
import com.google.errorprone.bugpatterns.javadoc.InvalidInlineTag;
import com.google.errorprone.bugpatterns.javadoc.InvalidLink;
import com.google.errorprone.bugpatterns.javadoc.InvalidParam;
import com.google.errorprone.bugpatterns.javadoc.InvalidSnippet;
import com.google.errorprone.bugpatterns.javadoc.InvalidThrows;
import com.google.errorprone.bugpatterns.javadoc.InvalidThrowsLink;
import com.google.errorprone.bugpatterns.javadoc.MalformedInlineTag;
Expand Down Expand Up @@ -966,6 +967,7 @@ public static ScannerSupplier warningChecks() {
InvalidInlineTag.class,
InvalidLink.class,
InvalidParam.class,
InvalidSnippet.class,
InvalidTargetingOnScopingAnnotation.class,
InvalidThrows.class,
InvalidThrowsLink.class,
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
/*
* Copyright 2024 The Error Prone Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.errorprone.bugpatterns.javadoc;

import static com.google.common.truth.TruthJUnit.assume;

import com.google.errorprone.CompilationTestHelper;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

/** Unit tests for {@link InvalidSnippet} bug pattern. */
@RunWith(JUnit4.class)
public final class InvalidSnippetTest {
private final CompilationTestHelper helper =
CompilationTestHelper.newInstance(InvalidSnippet.class, getClass());

@Test
public void snippetWithoutBody_butWithFile() {
assume().that(Runtime.version().feature()).isAtLeast(18);

helper
.addSourceLines(
"Test.java",
"""
/**
*
*
* {@snippet file="foo.java"}
*/
interface Test {}
""")
.doTest();
}

@Test
public void snippetWithColon() {
assume().that(Runtime.version().feature()).isAtLeast(18);

helper
.addSourceLines(
"Test.java",
"""
/**
*
*
* {@snippet :
* I have a colon
* }
*/
interface Test {}
""")
.doTest();
}
}

0 comments on commit 673aca3

Please sign in to comment.