-
Notifications
You must be signed in to change notification settings - Fork 4.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add helper for Markdown inline code escaping #18867
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with the PR in principle, but I would ask for some changes.
- Terminology nit: GH-flavored-markdown's official name for this is "code span", so let's rename the method to
markdownCodeSpan
- Please include the outermost backticks in the function's output. The only reason to not include them would be to allow concatenating multiple strings within a single span, e.g. to have
`${util.markdownCodeSpan(foo)}${util.markdownCodeSpan(bar)}`
in a template - but that is impossible to do safely (consider what happens when${util.markdownCodeSpan(foo)}
outputs a string with a terminal sequence of`
-s). Omitting the outermost onion layer of backticks is therefore a footgun for careless template writers. - We'd want a unit test in
src/test/java/com/google/devtools/build/skydoc/SkydocTest.javaon second thought, let's create a src/test/java/com/google/devtools/build/skydoc/MarkdownUtilTest.java
Note that I'm in the process of moving the renderer code from Bazel into the Stardoc repo; if you don't have time to make those changes, I can do them myself before the move (to avoid merge complications). |
The helper adds escaping to a string so that it can be embedded in a Markdown inline code segment delimited by backticks.
I made the changes you requested above, but I'm not sure what I would/would not have to do to support the move. |
Add missing license comment; make method static; make javadoc easier to read; run through formatter/linter.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks. Looks good. I took the liberty of adding the missing srcs filegroup and fixing some stylistic nits / linter suggestions.
@tetromino Thanks! Looks like there is a visibility issue with that though. |
Reverts #133 so that HTML escaping is not applied to Markdown. Instead, Markdown content such as docstrings can use HTML formatting and escape angle brackets with backslashes, HTML entities or inline code segments. Default values are embedded in inline code segments instead of `<code>` tags, which does not require escaping. As a result, docstrings behave just like regular Markdown contexts while default values are rendered without smart quotes and can contain both `<` and `` ` `` without causing escaping issues. Also includes tests based on #138. Fixes #137 Closes #138 Fixes #142 Closes #143 Requires bazelbuild/bazel#18867 Co-authored-by: Adam Azarchs <[email protected]>
The helper adds escaping to a string so that it can be embedded in a Markdown inline code segment delimited by backticks.