<p dir="auto">The docs pages for <a href="http://doc.rust-lang.org/std/marker/trait.Send.html" rel="nofollow">Send</a> and <a href="http://doc.rust-lang.org/std/marker/trait.Sync.html" rel="nofollow">Sync</a> show duplicated and incorrect items in the "Implementors" section.</p>
<p dir="auto">Specifically, an incorrect positive impl for <code class="notranslate">Rc</code> is present and the correct negative impl is present twice.<br>
Also, impls for <code class="notranslate">Arc</code> and <code class="notranslate">ArcInner</code> appear multiple times, with and without trait bounds and <code class="notranslate">where</code> clauses, with <code class="notranslate">Arc</code> having three appearances:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="impl&lt;T&gt; Send for Arc&lt;T&gt; where T: Send + Sync
impl&lt;T: Sync + Send&gt; Send for Arc&lt;T&gt;
impl&lt;T&gt; Send for Arc&lt;T&gt;"><pre class="notranslate"><span class="pl-k">impl</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">&gt;</span> <span class="pl-smi">Send</span> <span class="pl-k">for</span> <span class="pl-smi">Arc</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">&gt;</span> <span class="pl-k">where</span> <span class="pl-smi">T</span><span class="pl-kos">:</span> <span class="pl-smi">Send</span> + <span class="pl-smi">Sync</span><span class="pl-kos"></span>
<span class="pl-k">impl</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">:</span> <span class="pl-smi">Sync</span> + <span class="pl-smi">Send</span><span class="pl-kos">&gt;</span> <span class="pl-smi">Send</span> <span class="pl-k">for</span> <span class="pl-smi">Arc</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">&gt;</span><span class="pl-kos"></span>
<span class="pl-k">impl</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">&gt;</span> <span class="pl-smi">Send</span> <span class="pl-k">for</span> <span class="pl-smi">Arc</span><span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">&gt;</span><span class="pl-kos"></span></pre></div>
<h1 dir="auto">Issue</h1>
<p dir="auto">I noticed with a few of my crates that I have some redundancies between my docs and the code in the crate, specifically testcases. As a example, here <code class="notranslate">nice_example()</code> is duplicated:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="//! docs docs docs
//! docs docs docs
//! ```
//! fn nice_example() { ... }
//! ```

...

#[test]
fn nice_example() { ... }"><pre class="notranslate"><code class="notranslate">//! docs docs docs
//! docs docs docs
//! ```
//! fn nice_example() { ... }
//! ```

...

#[test]
fn nice_example() { ... }
</code></pre></div>
<p dir="auto">Now, there are right now two ways to deal with this:</p>
<ul dir="auto">
<li>Keep both copies
<ul dir="auto">
<li>Con: redundant copies, code can start drifting apart unintentionally.</li>
<li>Pro: If docs and tests diverge intentional, no additional work is needed.</li>
</ul>
</li>
<li>Remove the separate unit test copy of the code.
<ul dir="auto">
<li>Pro: The docs will get tested anyway</li>
<li>Pro: No redundancy</li>
<li>Con: Unit tests get split between two locations</li>
<li>Con: Unit tests start mixing with documentation, a change to either might cause changes to both and/or moving the unit test code back and forth between the docs and the crate.</li>
</ul>
</li>
</ul>
<p dir="auto">As an additional issue, having rust code in doc comments be highlighted as rust code is kinda complicated - or at least not implemented in most highlighters.</p>
<h1 dir="auto">Proposal</h1>
<p dir="auto">Have a way in doc comments to "include" the source code of an item in the documented crate, eg:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="//! docs docs docs
//! docs docs docs
//! ```
//! #rustdoc_include self::nice_example
//! ```

...

#[test]
fn nice_example() { ... }"><pre class="notranslate"><code class="notranslate">//! docs docs docs
//! docs docs docs
//! ```
//! #rustdoc_include self::nice_example
//! ```

...

#[test]
fn nice_example() { ... }
</code></pre></div>
<ul dir="auto">
<li>Pro: Only one copy of the actual code</li>
<li>Pro: No redundancy</li>
<li>Pro: Unit tests can be kept separate from the docs, even if they are nicely documented and used as example code in them.</li>
<li>Pro: If the docs don't want to use that particular code example anymore, only the reference needs<br>
to be deleted, and a nicely commented unit test remains.</li>
<li>The one copy of the code is outside doc comments, and thus will get highlighted correctly.</li>
<li>Con: More machinery for rustdoc to support</li>
<li>Con: Harder to read and write the documentation directly in the source.</li>
</ul>