Repository navigation
Fix Javadoc corruption from literal */ in parameter description - #11766
Merged
iscai-msft merged 4 commits intoAug 27, 2026
Merged
Conversation
Parameter descriptions are XML-escaped via CodeNamer.escapeXmlComment but not comment-escaped, so a literal */ (e.g. from an unconstrained */* content type doc) can prematurely close the generated /** ... */ Javadoc block, corrupting the rest of the file. CodeNamer.escapeComment already exists for this purpose; apply it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6a785543-019d-4b0c-9750-5affcfc900ee
microsoft-github-policy-service
Bot
added
the
emitter:client:java
iscai-msft
enabled auto-merge
August 26, 2026 15:51
Contributor
There was a problem hiding this comment.
Pull request overview
Fixes Java generator output corruption when parameter documentation contains the literal */ sequence, which can prematurely terminate generated /** ... */ Javadoc blocks and break compilation.
Changes:
- Apply comment-terminator escaping (
CodeNamer.escapeComment) inClientMethodTemplateBase#parameterDescriptionOrDefaultin addition to existing XML escaping. - Add a Chronus changelog entry documenting the fix for
@typespec/http-client-java.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ClientMethodTemplateBase.java | Escapes */ in parameter descriptions used in generated Javadoc tables to prevent source corruption. |
| .chronus/changes/fix-javadoc-content-type-escape-2026-08-26.md | Changelog entry for the Javadoc corruption fix in the Java HTTP client generator. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
You can try these changes here
|
- Move CodeNamer.escapeComment escaping into javadocTable so every cell (parameter/response-header name, type, description) is protected against a literal */ terminating the Javadoc block, not just parameter descriptions. - Add ClientMethodTemplateBaseTests covering the exact regression scenario (a description containing */*). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6a785543-019d-4b0c-9750-5affcfc900ee
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6a785543-019d-4b0c-9750-5affcfc900ee
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6a785543-019d-4b0c-9750-5affcfc900ee
Contributor
|
All changed packages have been documented.
Show changes
|
Weidong Xu (weidongxu-microsoft)
approved these changes
Aug 26, 2026
Weidong Xu (weidongxu-microsoft)
added a commit
to Azure/typespec-azure
that referenced
this pull request
Aug 31, 2026
## Summary - bump `@azure-tools/typespec-java` from `0.46.0` to `0.46.1` - publish the Java fixes synced in #5239 ## Included fixes - management `remove-model` generation (`microsoft/typespec#11698`) - Javadocs containing `*/` (`microsoft/typespec#11766`) - response headers following a constant header (`microsoft/typespec#11793`) --------- Copilot-Session: 0c853adf-d456-4d99-bacc-fd941aca7924
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
Fixes generated Java code corruption when a Javadoc table cell (parameter name/type/description, or response header name/type/description) contains a literal
*/sequence.Root cause
Values written into the optional-parameters and response-headers Javadoc tables are escaped for XML special characters via
CodeNamer.escapeXmlComment, but never comment-escaped. When a value embeds*/(for example, TCGC's Content-Type parameter doc for an unconstrainedHttp.Filecontent type, whosecontentTypesarray is["*/*"]), the literal*/prematurely closes the surrounding generated/** ... */Javadoc block. This corrupts the rest of the generated Java file and breaks compilation with a long cascade of parser errors.Fix
CodeNamer.escapeCommentalready exists and correctly escapes*/to*/, but it wasn't applied consistently. This change centralizes the escaping in the sharedClientMethodTemplateBase#javadocTablehelper so every cell value (not just parameter descriptions) is protected, alongside the existing XML escaping.Context
Found while fixing Azure/typespec-azure#5288 (Azure/typespec-azure#5306), where making the Content-Type parameter for default
Http.Filebodies client-visible (previously hidden as a constant) surfaced this latent Javadoc-escaping bug in CI.