Solving parsing errors for missing description in block tags

[0xbakry]

Base on discussion at #13043

We need to update grammar for @exception, @throws, @param so their arguments can be empty.

current grammar for exception and param tags:
https://github.com/checkstyle/checkstyle/blob/bd3c64badd4f1f7d58261af8dae9c40f9bf672b5/src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4#LL1144C1-L1148C56

EXCEPTION_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ CLASS_NAME (WS | NEWLINE)* ((WS | NEWLINE) description)?

PARAM_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ PARAMETER_NAME (WS | NEWLINE)* ((WS | NEWLINE) description)?

current for throw tag:
https://github.com/checkstyle/checkstyle/blob/bd3c64badd4f1f7d58261af8dae9c40f9bf672b5/src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4#LL1165C1-L1167C1

THROWS_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ CLASS_NAME (WS | NEWLINE)* ((WS | NEWLINE) description)?

CLI

$ cat config1.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name = "Checker">
    <property name="charset" value="UTF-8"/>

    <module name="TreeWalker">
       <module name="NonEmptyAtclauseDescription"/>
    </module>

</module>

$ cat Test1.java
public class Test1 {

  /**
   * @param
   */
  public void method(String a)
  {

  }
}

$ java -jar checkstyle-10.9.3-all.jar -c config1.xml Test1.java
Starting audit...
[ERROR] E:\Parse\Test1.java:6: Javadoc comment at column 3 has parse error. Details: no viable alternative at input '<EOF>' while parsing JAVADOC_TAG [NonEmptyAtclauseDescription]
Audit done.
Checkstyle ends with 1 errors.

Excepted:

Parser should be able to finish parsing without parser error.

[romani]

I am ok to ease parser as, no much people knows java doc syntax and we have to work after javac is passed but javadoc tool not executed yet.
But javadoc tool suppose to put error on this java doc.

[nrmancuso]

Few things here:

1. As we do javac for issue reporting for java code checks, we should show:
   a. javadoc tool output
   b. image/link to generated Javadoc
2. We need to be careful "easing the parser", as this will result in further ambiguity. Performance/overhead in Javadoc parser/lexer grammar is not good, we need to keep an eye on this.
3. If javadoc tool places error (not warning) on a Javadoc, we should not be expected to be able to parse it.

[romani]

If javadoc tool places error (not warning) on a Javadoc, we should not be expected to be able to parse it.

in general, yes. But lets imagine real life example of checkstyle usage.
You have IDE, you did update to method signature to add parameter, save/compile, checkstyle complains on no parameter in javadoc, you add it without description. Save/compile. Checkstyle violate javadoc as not parse able! It will take a while for user to catch a problem.

problem is that javadoc tool is almost never executed in dev cycle, as it is mostly for "assemble artifact" phase of build. Usually highly ignorable violations.

if we ease a bit strictness of our parser, at least for cases what description might be absent. We at least not throw in user obscure error message.

If we want to stay strict, we need to make error message to be clear for user, that will be another challenge.

[nrmancuso]

If we want to stay strict, we need to make error message to be clear for user, that will be another challenge.

Yes. Our error messages should be consistent. Our Javadoc parsing errors appear as check errors as opposed to normal checkstyle exception message when parsing Java code. If you agree we can open a new issue on this.

[romani]

We can open issue on this, but I do not see easy way to make it, we don't have good parser error messages even in java parser.
Before we make good to read messages, we can relax parser a bit and restore strict parsing as we have good messages.