Skip to content

Move violation comments out of Javadoc for all input files #19764

@lithops-zty

Description

@lithops-zty

Follow-up of #19756

Background

Putting violation comments (i.e. // violation xxx) inside Javadoc is considered a bad practice as they visually mix with target code. For example,

Bad

/**
 * The following is a bad tag.
 * @mytag Hello   // violation 'Unknown tag 'mytag'.'
 * // violation below 'Unknown tag 'mytag'.'
 * @mytag
 */
public class InputJavadocTypeBadTag {}

Good

// violation 4 lines below 'Unknown tag 'mytag'.'
// violation 4 lines below 'Unknown tag 'mytag'.'
/**
 * The following is a bad tag.
 * @mytag Hello
 * @mytag
 */
public class InputJavadocTypeBadTag {}

Task

Ensure no violation comments inside Javadoc for all existing input files.

Here is a list of existing input files to be fixed:

<!-- Input files with violation comments inside Javadoc, until https://github.com/checkstyle/checkstyle/issues/19764 -->
<suppress id="noViolationCommentsInJavadoc"
files="[\\/]chapter7javadoc[\\/]rule711generalform[\\/]InputCorrectJavadocLeadingAsteriskAlignment.java"/>
<suppress id="noViolationCommentsInJavadoc"
files="[\\/]chapter7javadoc[\\/]rule711generalform[\\/]InputFormattedCorrectJavadocLeadingAsteriskAlignment.java"/>

How to contribute

  1. Choose a package from the list;
  2. Move all violation comments out of Javadoc;
  3. Remove all related suppressions;
  4. Update violation line numbers inside unit test methods, if any changed.
  5. Send PR.

Notes

  1. Moving violating comments around requires adding (X lines) above/below to make sure they still reference the same line. You can refer to guide to specify violations for syntax.
  2. Make sure no input files exceed the limit of 120 lines.

Example of expected update #19766

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions