Make references optional for link and linkplain tags

[0xbakry]

Base on discussion at #12979

We need to update grammar for {@link}, {@linkplain} so their reference can be empty.

CLI:

$ cat Test1.java
class Test {

  /**
   * {@link}
   */
  public void method(String a)
  {

  }
}

$ 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>

$ java -jar checkstyle-10.9.3-all.jar -c config1.xml Test1.java
Starting audit...
[ERROR] E:\Parse\Test1.java:4: Javadoc comment at column 11 has parse error. 
Details: mismatched input '}' expecting {LEADING_ASTERISK, WS, NEWLINE} while 
parsing JAVADOC_INLINE_TAG [NonEmptyAtclauseDescription]
Audit done.
Checkstyle ends with 1 errors.

Excepted:
Have no parse error.

$ javadoc -d doc Test1.java
Loading source file Test1.java...
Constructing Javadoc information...
Creating destination directory: "doc\"
Standard Doclet version 11.0.18
Building tree for all the packages and classes...
Generating doc\Test1.html...
Test1.java:6: warning: no @param for a
  public void method(String a)
              ^
Generating doc\package-summary.html...
Generating doc\package-tree.html...
Generating doc\constant-values.html...
Building index for all the packages and classes...
Generating doc\overview-tree.html...
Generating doc\index-all.html...
Building index for all classes...
Generating doc\allclasses-index.html...
Generating doc\allpackages-index.html...
Generating doc\deprecated-list.html...
Building index for all classes...
Generating doc\allclasses.html...
Generating doc\allclasses.html...
Generating doc\index.html...
Generating doc\help-doc.html...
1 warning

Current grammar:
https://github.com/checkstyle/checkstyle/blob/477006469777636d28ec4cfbc453a987e02a8fcc/src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4#LL1181C1-L1184C46

LINK_LITERAL (WS | NEWLINE | LEADING_ASTERISK)+ reference (WS | NEWLINE)* ((WS | NEWLINE) description)?

LINKPLAIN_LITERAL (WS | NEWLINE | LEADING_ASTERISK)+ reference (WS | NEWLINE)* ((WS | NEWLINE) description)?

[romani]

Same as with java code, we have limitations.
For java code, code should be compileable, no error after javac.
For java doc comments , same, no errors on javadoc execution.

If we would like to extend parser to operate on content that javadoc tool highlighted as problematic, we need to know why we need to do this.
We usually do not do validation that base tool(javac, javadoc) already does.

Please share how javadoc tool react on such doc comment content.

[romani]

I thought one more time in demand no error on javadoc..... It might be too strict.
Everyone using javac in IDE. But nobody runs javadoc tool during development. So we might need to be able to parse reasonably correct comments. At least missed text for tag we should parse ok.

Please create separate issue on other tags that you think should be parable.

[0xbakry]

So we might need to be able to parse reasonably correct comments. At least missed text for tag we should parse ok.

Sorry but I didn't catch your point, do you mean we need to parse the missed parts even that will result an error in javadoc? or what?

[romani]

I mean if some java doc is missing description in block tag, and javadoc tool report error on such java doc comment, and checkstyle throw parsing error on such comment, we might need update parser to be able to finish parsing without parser error.

[aayushRedHat]

@romani Can i take this #13046 as there is not update on the pull request. It will help me to understand the Grammer, antlr-javadoc deeply

[romani]

@aayushRedHat, antrl issues are heavy, you can try, but do not hesitate to abandon PR is becomes too heavy. Better to slowly increase complexity of issues.