Add support to properly follow Rule 7.1.1 General Form in Google Style Guide Implementation #17778
Description
I have read check documentation: https://checkstyle.sourceforge.io/checks/javadoc/javadocleadingasteriskalign.html & https://checkstyle.org/google_style.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words
As per the google style guide rule 7.1.1 General Form, we're required to write javadoc in the following format:
/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
*/
public int method(String p1) { ... }We have JavadocLeadingAsteriskAlign Check which helps us to violate misaligned leading asterisk. This Check partially helps us to cover the rule. Why partially? I have explained the missing cases which this check doesn't cover later in the issue.
Current behavior of our style guide implementation:
/**
* Testing misaligned leading asterisks.
* Testing...
* Testing...
*/
public class Test {
/**
* Javadoc for instance variable.
*/
private String xyz;
/**
If leading asterisk is not present then identation is not checked.
// check does not handle such type of cases.
*/
private int age;
/**
Leading asterisk not present. */
// no leading asterisk, check does not handle such type of cases.
private void foo1() {}
/**
* Correct Indentation for leading asterisk. */
private void foo2() {}
/** Check does not handle such type of cases.
* Testing...
* Testing...
*/
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}$ java -jar .\checkstyle-11.0.1-all.jar -c .\google_checks.xml .\Test.java
Starting audit...
Audit done.
After using JavadocLeadingAsteriskAlign:
/**
* Testing misaligned leading asterisks.
* Testing... // violation
* Testing... // violation
*/
public class Test {
/**
* Javadoc for instance variable. // violation
*/ // violation
private String xyz;
/**
If leading asterisk is not present then identation is not checked.
// check does not handle such type of cases.
*/
private int age;
/**
Leading asterisk not present. */
// no leading asterisk, check does not handle such type of cases.
private void foo1() {}
/**
* Correct Indentation for leading asterisk. */
private void foo2() {}
/** Check does not handle such type of cases.
* Testing... // violation
* Testing... // violation
*/
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}$ java -jar .\checkstyle-11.0.1-all.jar -c .\google_checks.xml .\Test.java
Starting audit...
[WARN] D:\checkstyle-testing\.\Test.java:3:5: Leading asterisk has incorrect indentation level 5, expected is 2. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:4:1: Leading asterisk has incorrect indentation level 1, expected is 2. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:9:5: Leading asterisk has incorrect indentation level 5, expected is 4. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:10:5: Leading asterisk has incorrect indentation level 5, expected is 4. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:29:5: Leading asterisk has incorrect indentation level 5, expected is 4. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:30:1: Leading asterisk has incorrect indentation level 1, expected is 4. [JavadocLeadingAsteriskAlign]
[WARN] D:\checkstyle-testing\.\Test.java:31:2: Leading asterisk has incorrect indentation level 2, expected is 4. [JavadocLeadingAsteriskAlign]
Audit done.
Following cases which this check doesn't cover:
/** Check does not handle such type of cases.
* Testing... // violation
* Testing... // violation
*/In the above example, the check is not responsible for cases like: /** Check does not handle such type of cases.
The check doesn't violate when the javadoc content starts immediately after /**
/**
If leading asterisk is not present then identation is not checked.
// check does not handle such type of cases.
*/
private int age;If the leading asterisk is not present then check ignores that line. Should this be allowed? Maybe not. Style guide didn't explicitly mentioned that the leading asterisk should always be present but it said The basic formatting of Javadoc blocks is as seen in this example: and that example doesn't have missing leading asterisk, so I think it should always be present.
/**
* Correct Indentation for leading asterisk. */
private void foo2() {}*/ is not alone on the line. Again, style guide didn't mentioned anything about this but their example didn't cleared that is this allowed or not. But I think this should not be allowed, the */ should always be alone on the line.