Skip to content

Format MOE strip markers in javadoc like any other HTML comment - #155

Merged
abashev merged 1 commit into
21.X.Xfrom
remove-moe-javadoc-markers
Oct 25, 2026
Merged

abashev merged 1 commit into
21.X.Xfrom
remove-moe-javadoc-markers

Conversation

@abashev

@abashev abashev commented Oct 25, 2026

Copy link
Copy Markdown
Collaborator

google/MOE, the tool whose <!-- MOE:begin_intracomment_strip --> and <!-- MOE:end_intracomment_strip --> markers the javadoc formatter recognised, has been dead for years; #150 drops the line-comment rule for // MOE:. This removes the javadoc side: the two token types, the lexer patterns, the formatter cases and the writer state that queued a begin marker until the next token and remembered its indent for the end marker. Both markers now take the ordinary HTML comment path: a line of their own, at the indent of the text around them. Once #150 is in as well, no MOE reference is left in src/main.

What changes for a javadoc that still carries the markers:

  • A blank line that the tag after a begin marker asks for comes after the marker, not before it.
  • A marker inside or between footer tags is a continuation line of the tag it follows, so it is indented four columns; the old code wrote the begin marker at the indent of the next token and gave the end marker that same indent.
  • A begin marker that closes the comment without an end marker is kept; the old code queued it and never flushed it, so /** Foo. <!-- MOE:begin_intracomment_strip --> */ came out as /** Foo. */.

Before, for the footer tags of the test:

 * @param user the person to teleport.
 *     <!-- MOE:begin_intracomment_strip -->
 *     Users must sign go/deatomize-waiver ahead of time.
 *     <!-- MOE:end_intracomment_strip -->
 * <!-- MOE:begin_intracomment_strip -->
 * @deprecated Sometimes turns the user into a goat.
 * <!-- MOE:end_intracomment_strip -->

After:

 * @param user the person to teleport.
 *     <!-- MOE:begin_intracomment_strip -->
 *     Users must sign go/deatomize-waiver ahead of time.
 *     <!-- MOE:end_intracomment_strip -->
 *     <!-- MOE:begin_intracomment_strip -->
 * @deprecated Sometimes turns the user into a goat.
 *     <!-- MOE:end_intracomment_strip -->

Tests

Written first: moeStripMarkersAreOrdinaryHtmlComments failed before the change, with the old layout as its actual output. The three cases that only guarded the begin/end pairing against exploding (moeCommentBeginOnlyInMiddleOfDoc, moeCommentBeginOnlyAtEndOfDoc, moeCommentEndOnly) are gone.

Verification

  • ./gradlew test over all modules is green; ./gradlew formatDiff changes nothing; a full recompile gives the same 119 javac warnings before and after.
  • JDK 21 corpus, 15,747 files, formatted with javadoc formatting on: no file differs between 21.X.X and this branch, and the JDK carries no MOE marker. The CLI never enables javadoc formatting (JavaFormatterOptions defaults it off and Main has no flag for it), so the usual -i run cannot see a javadoc change; the comparison ran through Formatter with formatJavadoc(true) plus the CLI's import and reflow passes.

google/MOE, the tool whose intracomment-strip markers the javadoc formatter
recognised, has been dead for years. The lexer no longer gives
`<!-- MOE:begin_intracomment_strip -->` and `<!-- MOE:end_intracomment_strip -->`
token types of their own, and the writer loses the state that queued the begin
marker until the next token and remembered its indent for the end marker: both
markers now take the HTML comment path, a line of their own at the indent of
the text around them.

The layouts the old test pinned change in two places: a blank line the next
tag asks for comes after the begin marker instead of before it, and a marker
inside or between footer tags is indented as a continuation line of the tag it
follows. A begin marker that closes the comment without an end marker is kept
instead of silently deleted.

The test was written first: moeStripMarkersAreOrdinaryHtmlComments failed
before the change; the three cases that only guarded the begin/end pairing
against exploding are gone. None of the 15,747 JDK 21 sources changes with
javadoc formatting on; the JDK carries no MOE markers.
@abashev
abashev merged commit a13b036 into 21.X.X Oct 25, 2026
17 checks passed
@abashev
abashev deleted the remove-moe-javadoc-markers branch October 25, 2026 19:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant