[Julia] Fix docstring parameter formatting with backticks #22190
Conversation
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
Wrap parameter names in backticks in generated Julia client docstrings to prevent markdown from misinterpreting underscores as italic formatting. This fixes an issue where parameter names like `pet_id`, `api_key`, and `additional_metadata` would render incorrectly in documentation, with underscores being treated as markdown italic markers instead of literal characters. Related issue: JuliaComputing/OpenAPI.jl#72
|
please follow step 3 in the PR checklist to update the samples |
Extend backtick formatting to markdown documentation templates for both Julia client and server generators. This ensures consistent markdown rendering of identifiers with underscores. Changes: - julia-client/api_doc.mustache: Add backticks to function signatures, parameter names, types, and return types in markdown API docs - julia-server/api_doc.mustache: Same changes for server API docs - julia-client/model_doc.mustache: Add backticks to property names and types in markdown model documentation - julia-server/model_doc.mustache: Same changes for server model docs All generated markdown files now properly display identifiers like `pet_id`, `Custom_Type`, `update_pet_with_form` with literal underscores instead of broken italic formatting. Related to JuliaComputing/OpenAPI.jl#72
|
thanks for the pr and updating the samples cc @tanmaykm for review |
wing328
reviewed
Oct 23, 2025
| @@ -0,0 +1,98 @@ | |||
| # Plan: Add Backticks to All Julia Template Documentation | |||
There was a problem hiding this comment.
is this file required as part of the change?
There was a problem hiding this comment.
Definitely not - will put some work in on this tomorrow.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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
Wraps all identifiers (parameter names, function names, data types, property names, return types) in backticks in Julia client and server documentation to prevent markdown from interpreting underscores as italic formatting.
Problem
Identifiers like
pet_id,api_key,Custom_Typerender incorrectly in markdown documentation because underscores are treated as italic markers.Solution
Added backticks to all identifier references across Julia templates:
Templates Modified
Code docstrings:
julia-client/api.mustache- Function docstrings in generated Julia codeMarkdown API documentation:
julia-client/api_doc.mustache- Function signatures, parameters, return typesjulia-server/api_doc.mustache- Same for serverMarkdown model documentation:
julia-client/model_doc.mustache- Property names and typesjulia-server/model_doc.mustache- Same for serverSamples Regenerated
Both Julia client and server samples updated to demonstrate the fix.
Example
Before:
Renders with broken italics: petid
After:
Renders correctly with literal underscores.
Fixes JuliaComputing/OpenAPI.jl#72