rustdoc codeblock hash escape #51803
Conversation
|
(rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
killercup
added
the
T-rustdoc
| @@ -91,15 +91,15 @@ impl<'a> Line<'a> { | |||
| fn map_line(s: &str) -> Line { | |||
| let trimmed = s.trim(); | |||
| if trimmed.starts_with("##") { | |||
| Line::Shown(&trimmed[1..]) | |||
| Line::Shown(Cow::Owned(s.replacen("##", "#", 1))) | |||
There was a problem hiding this comment.
Two things:
- Wait, there is no Cow-returning
replacenyet? Might be a nice thing to have, since it's pretty concise. Not relevant here, though. - Given that we are in the branch where the string starts with
##, isn't replacing the two hash signs with one the same as&s[1..]?
There was a problem hiding this comment.
- Agreed.
- It is not the same, because of leading whitespace. We check if
trimmedstarts with##, nots.
|
Ping from triage, @QuietMisdreavus / @rust-lang/rustdoc: This PR requires your review. |
|
I think it should be documented in the rustdoc book. Can you add it in there please? |
|
@GuillaumeGomez done — however, it will not render correctly until rust-lang/mdBook#719 gets merged. |
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
|
I think the sentence is badly turned. It'd be better to precise that only the first |
|
@GuillaumeGomez good point — I've updated it. |
|
Thanks! @bors: r+ |
|
📌 Commit ff2ff2b has been approved by |
bors
added
S-waiting-on-bors
…omez
rustdoc codeblock hash escape
So that docstring text such as the following (in a code block) can be created ergonomically:
```rust
let s = "
foo
# bar
baz
";
```
Such code in a docstring hide the <code> # bar</code> line.
Previously, using two consecutive hashes <code> ## bar</code> would turn the line into _shown_ `# bar`, losing the leading whitespace. A line of code like <code> # bar</code> (such as in the example above) **could not be represented** in the docstring text.
This commit makes the two consecutive hashes not also trim the leading whitespace — the two hashes simply **escape** into a single hash and do not hide the line, leaving the rest of that line unaffected. The new docstring text to achieve the above code block is:
```rust
/// ```
/// let s = "
/// foo
/// ## bar
/// baz
/// ";
/// ```
```
|
☀️ Test successful - status-appveyor, status-travis |
pending merge of rust-lang/rust#51803
So that docstring text such as the following (in a code block) can be created ergonomically:
Such code in a docstring hide the
# barline.Previously, using two consecutive hashes
## barwould turn the line into shown# bar, losing the leading whitespace. A line of code like# bar(such as in the example above) could not be represented in the docstring text.This commit makes the two consecutive hashes not also trim the leading whitespace — the two hashes simply escape into a single hash and do not hide the line, leaving the rest of that line unaffected. The new docstring text to achieve the above code block is: