New markdown parser breaks when documenting xml5ever as part of Servo build

[jdm]

I believe the switch broke the doc build for xml5ever. We now see this output:

 Documenting xml5ever v0.4.2
error: character literal may only contain one codepoint: '&
 --> <stdin>:1:6
  |
1 | <tag>'&-quotes'</tag>   becomes      <tag>'&amp;-quotes'</tag>
  |      ^^

error: Could not document `xml5ever`.

Tracking in servo/servo#16213 as well.

Of course, I can't reproduce this when running cargo doc on the xml5ever subdirectory of https://github.com/servo/html5ever/. I can only reproduce this as part of running ./mach doc in a Servo clone. :/

[jdm]

The documentation in question is:

/// Writes given text into the Serializer, escaping it,
/// depending on where the text is written inside the tag or attribute value.
///
/// For example
///```
///    <tag>'&-quotes'</tag>   becomes      <tag>'&amp;-quotes'</tag>
///    <tag = "'&-quotes'">    becomes      <tag = "&apos;&amp;-quotes&apos;"
///```

[steveklabnik]

I think I know what this is. Previously, this was not interpreted as a real code block, aka a doc test. But now, it is.

Try

```text

instead.

(Also, I'd give it some space, so like this:

/// For example
///
/// ```text

(I think the text matters more, though.)

[steveklabnik]

Yeah, look at this on babelmark

Hoedown is not part of bablemark, but 10 implementations consider this a <p>, and 16 (including CommonMark) consider it a <p><pre>. I'm willing to bet hoedown would be one of the former.

[steveklabnik]

Of course, I can't reproduce this when running cargo doc on the xml5ever subdirectory of https://github.com/servo/html5ever/. I can only reproduce this as part of running ./mach doc in a Servo clone. :/

This part kinda bugs me. you're sure that cargo doc is with the latest nightly?

[jdm]

Absolutely.

[jdm]

godot2:xml5ever jdm$ cargo doc
 Documenting void v1.0.2
   Compiling matches v0.1.4
   Compiling lazy_static v0.2.5
   Compiling rustc-serialize v0.3.23
 Documenting encoding_index_tests v0.1.4
   Compiling siphasher v0.2.2
 Documenting matches v0.1.4
   Compiling encoding_index_tests v0.1.4
 Documenting string_cache_shared v0.3.0
   Compiling utf-8 v0.6.0
   Compiling mac v0.1.1
   Compiling phf_shared v0.7.21
 Documenting encoding-index-simpchinese v1.20141219.5
 Documenting encoding-index-japanese v1.20141219.5
 Documenting encoding-index-korean v1.20141219.5
   Compiling libc v0.2.21
 Documenting siphasher v0.2.2
 Documenting utf-8 v0.6.0
 Documenting log v0.3.7
 Documenting encoding-index-tradchinese v1.20141219.5
 Documenting mac v0.1.1
   Compiling encoding-index-tradchinese v1.20141219.5
   Compiling encoding-index-simpchinese v1.20141219.5
   Compiling time v0.1.36
   Compiling encoding-index-singlebyte v1.20141219.5
 Documenting serde v0.9.12
 Documenting phf_shared v0.7.21
   Compiling log v0.3.7
 Documenting libc v0.2.21
   Compiling encoding-index-korean v1.20141219.5
   Compiling phf v0.7.21
 Documenting phf v0.7.21
 Documenting lazy_static v0.2.5
   Compiling void v1.0.2
 Documenting unreachable v0.1.1
   Compiling unreachable v0.1.1
   Compiling rand v0.3.15
 Documenting debug_unreachable v0.1.1
   Compiling encoding-index-japanese v1.20141219.5
 Documenting encoding-index-singlebyte v1.20141219.5
   Compiling serde v0.9.12
   Compiling encoding v0.2.33
 Documenting encoding v0.2.33
   Compiling debug_unreachable v0.1.1
 Documenting futf v0.1.3
   Compiling futf v0.1.3
   Compiling phf_generator v0.7.21
   Compiling string_cache_shared v0.3.0
   Compiling phf_codegen v0.7.21
   Compiling string_cache_codegen v0.3.1
 Documenting time v0.1.36
   Compiling xml5ever v0.4.2 (file:///Users/jdm/src/html5ever/xml5ever)
   Compiling tendril v0.2.3
 Documenting tendril v0.2.3
   Compiling html5ever-atoms v0.2.2
   Compiling string_cache v0.4.0
 Documenting string_cache v0.4.0
 Documenting html5ever-atoms v0.2.2
 Documenting xml5ever v0.4.2 (file:///Users/jdm/src/html5ever/xml5ever)
    Finished dev [unoptimized] target(s) in 18.41 secs
godot2:xml5ever jdm$ rustdoc --versin
rustdoc: Unrecognized option: 'versin'.
Try 'rustdoc --help' for more information.
godot2:xml5ever jdm$ rustdoc --version
rustdoc 1.18.0-nightly (40feadb96 2017-03-31)
godot2:xml5ever jdm$ cargo --version
cargo 0.19.0-nightly (4e95c6b41 2017-03-23)
godot2:xml5ever jdm$ rustc --version
rustc 1.18.0-nightly (40feadb96 2017-03-31)

[nagisa]

cargo doc by itself does not try to run doctests, but mach doc may do that.

[steveklabnik]

Ahhh, right. It'd only run the tests on `cargo test`.

[GuillaumeGomez]

So I guess the issue is "fixed" then, no?

[kzys]

+1 for resolving this issue.

[GuillaumeGomez]

I'm not sure if it's still broken or not. Didn't hear back from servo about this since then...

[jdm]

We have definitely had working doc builds since I filed this.