checkstyle / checkstyle/checkstyle
Move violation comments out of Javadoc for all input files
- 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
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