checkstyle / checkstyle/checkstyle

Move violation comments out of Javadoc for all input files

Open
#19,764 19 comments 0 reactions 0 assignees View on GitHub
approved good second issue miscellaneous
Dominant language
Java
Stars
9.6k
Forks
4.2k
Avg merge
22h 23m
Merged PRs (30d)
232

Description

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**
```java
/**
* The following is a bad tag.
* @mytag Hello // violation 'Unknown tag 'mytag'.'
* // violation below 'Unknown tag 'mytag'.'
* @mytag
*/
public class InputJavadocTypeBadTag {}
```

**Good**
```java
// 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:
https://github.com/checkstyle/checkstyle/blob/b884b9a31b47be7b6e1a4d7d3b0f469a36e62637/config/checkstyle-input-suppressions.xml#L67-L71

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](https://github.com/checkstyle/checkstyle/blob/master/docs/specifying-violations.md) for syntax.
2. Make sure no input files exceed the limit of 120 lines.

Example of expected update https://github.com/checkstyle/checkstyle/pull/19766

Contributor guide

Open the contributing guide

Research direction

Start with the package list in config/checkstyle-input-suppressions.xml and review the existing input files selected from it. Move violation comments out of Javadoc, remove related suppressions, update affected unit-test line numbers, and verify files stay within 120 lines and no Javadoc contains violation comments.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
testing-qa
Issue type
Refactor
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.