Drop JavadocParagraph rule to resolve Spotless conflict#3
Open
khatchad wants to merge 1 commit into
Open
Conversation
The `JavadocParagraph` Checkstyle rule requires a blank Javadoc line before each `<p>` tag. Spotless's Eclipse Javadoc formatter strips exactly those blank lines on `spotless:apply`. Result: writing the conventional `<p>` Javadoc style (as used by the JDK and most Java libraries) is unreachable in repos consuming this config—every contributor hits the same wall and burns time discovering the workaround. The rule's signal is low: blank-line-before-`<p>` is a stylistic micro-preference, not a correctness check. Drop it. Blank Javadoc lines as paragraph breaks remain a valid alternative when contributors prefer that style. Surfaced during the ponder-lab/Hybridize-Functions-Refactoring submodule bump (ponder-lab/Hybridize-Functions-Refactoring#531), where 10 pre-existing `<p>` violations had to be rewritten as blank-line breaks to satisfy both tools. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Removes the JavadocParagraph Checkstyle rule from the shared Checkstyle configuration to eliminate a known incompatibility with Spotless’s Eclipse Javadoc formatter, allowing the conventional <p> paragraph style in Javadocs.
Changes:
- Deleted the
JavadocParagraphmodule fromponder-checkstyle.xml. - Added an inline XML comment documenting the Spotless conflict and the rationale for disabling the rule.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Remove the
JavadocParagraphrule fromponder-checkstyle.xml. It conflicts with Spotless's Eclipse Javadoc formatter, making the conventional<p>Javadoc style unreachable in repos consuming this config.Why
JavadocParagraph) says<p>with preceding blank line<p>"<p>without preceding blank line<p>)The first two rows are the standard JDK/Guava/most-Java-libraries form. Forcing the third form across every consumer of this config is friction with no documentary benefit—blank-line-before-
<p>is a stylistic micro-preference, not correctness.Effect
<p>paragraph breaks (still spotless-tolerated).<p>) keep that style too.SummaryJavadoc(first sentence ends with a period) stays in place—that one carries real signal.Cross-Refs
Formattingsubmodule and clean up accumulated Javadoc violations Hybridize-Functions-Refactoring#531—where the conflict surfaced. 10 pre-existing<p>violations had to be rewritten as blank-line breaks to satisfy both tools; with this drop landed, future Hybridize contributors won't hit the same wall.