Skip to content

Javadoc: drop an empty trailing <p> tag #237

Open

Description

@abashev

Upstream: google/google-java-format#1526
Kind: bug | Priority: low

google-java-format#1526 (open, first-time contributor, no comments yet) makes the Javadoc lexer remove a <p> that is the last significant token of a classic Javadoc comment, so the formatter stops leaving a dangling paragraph tag. It claims to fix the long-standing upstream issue google-java-format issue 1150. The PR adds a small pass to JavadocLexer.generateTokens() (skips the end-of-comment token and trailing whitespace, drops a final paragraph-open token) plus one test in JavadocFormattingTest.

Why it matters to us: our JavadocLexer has the same structure (generateTokens() ends with optionalizeSpacesAfterLinks and deindentPreCodeBlocks), and our JavadocWriter.writeParagraphOpen only ignores a <p> when nothing significant was written yet. A trailing <p> after real text therefore requests a blank line and is written out. This is a harmless cosmetic cleanup, and the diff should apply almost as is.

Before (how it is formatted today; derived from reading our writer, not by running it):

/**
 * The client's first name.
 *
 * <p>
 */
class Test {}

After (with the change):

/** The client's first name. */
class Test {}

Affected files in our repo: open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java (generateTokens), JavadocWriter.java (writeParagraphOpen), and the Javadoc formatting tests.

Suggested action: watch the PR; if it is accepted or stays unchallenged, adopt the idea (port the lexer pass and its test, checking that the /** ... */ one-liner collapse happens and that the pass is idempotent with markdown comments).


Filed from an upstream-watch ticket after manual review.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions