New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JavadocMethod: No error for a misplaced javadoc tag #4701

Closed
pbludov opened this Issue Jul 12, 2017 · 4 comments

Comments

Projects
None yet
4 participants
@pbludov
Collaborator

pbludov commented Jul 12, 2017

$ javac TestClass.java

$ cat TestClass.java

package test;

public class TestClass {

  /**
   * Method description.
   *
   * @param foo
   *        Parameter description. @return Error is expected here.
   */
  public int method(int foo) {
    return foo;
  }
}

$ cat TestConfig.xml

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
  "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
  "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">

<module name="Checker">
  <property name="charset" value="UTF-8"/>
  <module name="TreeWalker">
    <module name="JavadocMethod">
       <property name="allowMissingReturnTag" value="false"/>
    </module>
  </module>
</module>

$ java -jar checkstyle-8.0-all.jar -c TestConfig.xml TestClass.java
Starting audit...
Audit done.

$ java -jar checkstyle-8.0-all.jar -J TestClass.java

PACKAGE_DEF -> package [1:0]
|--ANNOTATIONS -> ANNOTATIONS [1:8]
|--IDENT -> test [1:8]
`--SEMI -> ; [1:12]
CLASS_DEF -> CLASS_DEF [3:0]
|--MODIFIERS -> MODIFIERS [3:0]
|   `--LITERAL_PUBLIC -> public [3:0]
|--LITERAL_CLASS -> class [3:7]
|--IDENT -> TestClass [3:13]
`--OBJBLOCK -> OBJBLOCK [3:23]
    |--LCURLY -> { [3:23]
    |--METHOD_DEF -> METHOD_DEF [11:2]
    |   |--MODIFIERS -> MODIFIERS [11:2]
    |   |   |--BLOCK_COMMENT_BEGIN -> /* [5:2]
    |   |   |   |--COMMENT_CONTENT -> *\n   * Method description.\n   *\n   * @param foo\n   *        Parameter description. @return Error is expected here.\n    [5:4]
    |   |   |   |   `--JAVADOC -> JAVADOC [5:5]
    |   |   |   |       |--NEWLINE -> \n [5:5]
    |   |   |   |       |--LEADING_ASTERISK ->    * [6:0]
    |   |   |   |       |--TEXT ->  Method description. [6:4]
    |   |   |   |       |--NEWLINE -> \n [6:24]
    |   |   |   |       |--LEADING_ASTERISK ->    * [7:0]
    |   |   |   |       |--NEWLINE -> \n [7:4]
    |   |   |   |       |--LEADING_ASTERISK ->    * [8:0]
    |   |   |   |       |--WS ->   [8:4]
    |   |   |   |       |--JAVADOC_TAG -> JAVADOC_TAG [8:5]
    |   |   |   |       |   |--PARAM_LITERAL -> @param [8:5]
    |   |   |   |       |   |--WS ->   [8:11]
    |   |   |   |       |   |--PARAMETER_NAME -> foo [8:12]
    |   |   |   |       |   |--NEWLINE -> \n [8:15]
    |   |   |   |       |   `--DESCRIPTION -> DESCRIPTION [9:0]
    |   |   |   |       |       |--LEADING_ASTERISK ->    * [9:0]
    |   |   |   |       |       |--TEXT ->         Parameter description. @return Error is expected here. [9:4]
    |   |   |   |       |       |--NEWLINE -> \n [9:66]
    |   |   |   |       |       `--TEXT ->     [10:0]
    |   |   |   |       `--EOF -> <EOF> [10:3]
    |   |   |   `--BLOCK_COMMENT_END -> */ [10:3]

$ javadoc TestClass.java
Loading source file TestClass.java...
Constructing Javadoc information...
Standard Doclet version 1.8.0_131
Building tree for all the packages and classes...
Generating ./test/TestClass.html...
TestClass.java:11: warning: no @return
public int method(int foo) {
^

The javadoc tag is present, but not in the right place.
As usual, the bug is related to the regex based parsing of java doc comments.

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Jul 12, 2017

Member

the bug is related to the regex based parsing of java doc comments.

Yes.

Member

rnveach commented Jul 12, 2017

the bug is related to the regex based parsing of java doc comments.

Yes.

@pbludov

This comment has been minimized.

Show comment
Hide comment
@pbludov

pbludov Nov 17, 2017

Collaborator

The right solution would be to remake the JavadocMethodCheck with AbstractJavadocCheck, but the JavadocMethodCheck is an AbstractTypeAwareCheck, so it will be hard to do.

A good enough solution is to make the JavadocMethodCheck regular expression a bit smarter. The javadoc specs requires that a block tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. Thus, it can be fixed by adding the prefix "^\s**?\s*" to each regular expression that JavadocMethodCheck uses.

Collaborator

pbludov commented Nov 17, 2017

The right solution would be to remake the JavadocMethodCheck with AbstractJavadocCheck, but the JavadocMethodCheck is an AbstractTypeAwareCheck, so it will be hard to do.

A good enough solution is to make the JavadocMethodCheck regular expression a bit smarter. The javadoc specs requires that a block tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. Thus, it can be fixed by adding the prefix "^\s**?\s*" to each regular expression that JavadocMethodCheck uses.

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Nov 17, 2017

Member

but the JavadocMethodCheck is an AbstractTypeAwareCheck, so it will be hard to do.

AbstractTypeAwareCheck is deprecated so we will lose some functionality regardless, but the rest of the check can be remade.

A good enough solution is to make the JavadocMethodCheck regular expression a bit smarter.

Anyone is welcome to do this, but it will be pointless once the check is remade which is why we don't actively do this.

Member

rnveach commented Nov 17, 2017

but the JavadocMethodCheck is an AbstractTypeAwareCheck, so it will be hard to do.

AbstractTypeAwareCheck is deprecated so we will lose some functionality regardless, but the rest of the check can be remade.

A good enough solution is to make the JavadocMethodCheck regular expression a bit smarter.

Anyone is welcome to do this, but it will be pointless once the check is remade which is why we don't actively do this.

@romani romani added the approved label Nov 25, 2017

@romani romani changed the title from No error for a misplaced javadoc tag to JavadocMethod: No error for a misplaced javadoc tag Nov 25, 2017

rnveach added a commit that referenced this issue Nov 28, 2017

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Nov 28, 2017

Member

Fix was merged

Member

rnveach commented Nov 28, 2017

Fix was merged

@rnveach rnveach closed this Nov 28, 2017

@rnveach rnveach added the bug label Nov 28, 2017

@rnveach rnveach added this to the 8.6 milestone Nov 28, 2017

timurt added a commit to timurt/checkstyle that referenced this issue Dec 19, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment