<p dir="auto">This seems to be a very inconsistant issue, but I think it's related to macros.</p>
<p dir="auto">Here's an example of a list of comments that don't get parsed properly:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="bitflags! {
    flags Tests: Test {
        /// Test
        static TestA = 0x80,
        // TODO: Document this.
        static TestB          = 0x40
    }
}"><pre class="notranslate"><span class="pl-en">bitflags</span><span class="pl-en">!</span> <span class="pl-kos">{</span>
    flags <span class="pl-v">Tests</span>: <span class="pl-v">Test</span> <span class="pl-kos">{</span>
        <span class="pl-c">/// Test</span>
        <span class="pl-k">static</span> <span class="pl-v">TestA</span> = <span class="pl-c1">0x80</span>,
        <span class="pl-c">// TODO: Document this.</span>
        <span class="pl-k">static</span> <span class="pl-v">TestB</span>          = <span class="pl-c1">0x40</span>
    <span class="pl-kos">}</span>
<span class="pl-kos">}</span></pre></div>
<p dir="auto">This code will error saying "no rules expected the token <code class="notranslate">/// Test</code>".<br>
<a href="http://is.gd/Zkpgvd" rel="nofollow">http://is.gd/Zkpgvd</a></p>
<p dir="auto">This would allow doc comments to parse them as <code class="notranslate">$_:meta</code> elements in macro invocations. This is useful for example with <code class="notranslate">bitflags!</code>:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="bitflags! {
    #[doc = &quot;Some flags&quot;]
    #[doc = &quot;&quot;]
    #[doc = &quot;A new line&quot;]
    #[deriving(Show)]
    flags Flags: u32 {
        #[doc = &quot;Flag A&quot;]
        static FlagA = 0x00000001,
        #[doc = &quot;Flag B&quot;]
        static FlagB = 0x00000010
    }
}"><pre class="notranslate"><span class="pl-en">bitflags</span><span class="pl-en">!</span> <span class="pl-kos">{</span>
    #<span class="pl-kos">[</span>doc = <span class="pl-s">"Some flags"</span><span class="pl-kos">]</span>
    #<span class="pl-kos">[</span>doc = <span class="pl-s">""</span><span class="pl-kos">]</span>
    #<span class="pl-kos">[</span>doc = <span class="pl-s">"A new line"</span><span class="pl-kos">]</span>
    #<span class="pl-kos">[</span>deriving<span class="pl-kos">(</span><span class="pl-v">Show</span><span class="pl-kos">)</span><span class="pl-kos">]</span>
    flags <span class="pl-v">Flags</span>: <span class="pl-smi">u32</span> <span class="pl-kos">{</span>
        #<span class="pl-kos">[</span>doc = <span class="pl-s">"Flag A"</span><span class="pl-kos">]</span>
        <span class="pl-k">static</span> <span class="pl-v">FlagA</span> = <span class="pl-c1">0x00000001</span>,
        #<span class="pl-kos">[</span>doc = <span class="pl-s">"Flag B"</span><span class="pl-kos">]</span>
        <span class="pl-k">static</span> <span class="pl-v">FlagB</span> = <span class="pl-c1">0x00000010</span>
    <span class="pl-kos">}</span>
<span class="pl-kos">}</span></pre></div>
<p dir="auto">vs:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="bitflags! {
    /// Some flags
    ///
    /// A new line
    #[deriving(Show)]
    flags Flags: u32 {
        /// Flag A
        static FlagA = 0x00000001,
        /// Flag B
        static FlagB = 0x00000010
    }
}"><pre class="notranslate"><span class="pl-en">bitflags</span><span class="pl-en">!</span> <span class="pl-kos">{</span>
    <span class="pl-c">/// Some flags</span>
    ///
    <span class="pl-c">/// A new line</span>
    #<span class="pl-kos">[</span>deriving<span class="pl-kos">(</span><span class="pl-v">Show</span><span class="pl-kos">)</span><span class="pl-kos">]</span>
    flags <span class="pl-v">Flags</span>: <span class="pl-smi">u32</span> <span class="pl-kos">{</span>
        <span class="pl-c">/// Flag A</span>
        <span class="pl-k">static</span> <span class="pl-v">FlagA</span> = <span class="pl-c1">0x00000001</span>,
        <span class="pl-c">/// Flag B</span>
        <span class="pl-k">static</span> <span class="pl-v">FlagB</span> = <span class="pl-c1">0x00000010</span>
    <span class="pl-kos">}</span>
<span class="pl-kos">}</span></pre></div>
<p dir="auto">Where the <code class="notranslate">bitflags!</code> <a href="https://github.com/mozilla/rust/blob/master/src/libstd/bitflags.rs#L108-L110">match rule</a> is defined as:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="($(#[$attr:meta])* flags $BitFlags:ident: $T:ty {
    $($(#[$Flag_attr:meta])* static $Flag:ident = $value:expr),+
})"><pre class="notranslate"><span class="pl-kos">(</span>$<span class="pl-kos">(</span><span class="pl-c1">#<span class="pl-kos">[</span>$attr<span class="pl-kos">:</span>meta<span class="pl-kos">]</span></span><span class="pl-kos">)</span><span class="pl-c1">*</span> flags $BitFlags<span class="pl-kos">:</span>ident<span class="pl-kos">:</span> $T<span class="pl-kos">:</span>ty <span class="pl-kos">{</span>
    $<span class="pl-kos">(</span>$<span class="pl-kos">(</span><span class="pl-c1">#<span class="pl-kos">[</span>$Flag_attr<span class="pl-kos">:</span>meta<span class="pl-kos">]</span></span><span class="pl-kos">)</span><span class="pl-c1">*</span> static $Flag<span class="pl-kos">:</span>ident = $value<span class="pl-kos">:</span>expr<span class="pl-kos">)</span><span class="pl-kos">,</span>+
<span class="pl-kos">}</span><span class="pl-kos">)</span></pre></div>