<p dir="auto">The example of the <code class="notranslate">std::num</code> module speaks for itself. I can count at least three grammatical forms among the function descriptions:</p>
<ul dir="auto">
<li>indicative form (<code class="notranslate">abs: Computes the absolute value.</code>);</li>
<li>imperative form (<code class="notranslate">acos: Compute the arccosine of the number.</code>);</li>
<li>noun phrase (<code class="notranslate">abs_sub: The positive difference of two numbers.</code> or <code class="notranslate">cos: Cosine function</code>).</li>
</ul>
<p dir="auto">The various style guides (<a href="https://github.com/mozilla/rust/wiki/Note-style-guide">https://github.com/mozilla/rust/wiki/Note-style-guide</a>, <a href="https://github.com/mozilla/rust/wiki/Doc-using-rustdoc">https://github.com/mozilla/rust/wiki/Doc-using-rustdoc</a> and <a href="http://static.rust-lang.org/doc/master/rustdoc.html" rel="nofollow">http://static.rust-lang.org/doc/master/rustdoc.html</a>) recommend writing "sentences that begin with capital letters and end in a period" but do not mention how the sentences should be formed.</p>
<p dir="auto">I am willing to work on making all this coherent but a convention should be fixed first.</p>
<p dir="auto">With a lot of library code expected to change before the 1.0 release, it doesn't make much sense to do this now, but the core and std libraries should use a consistent style for API documentation. The <a href="https://github.com/mozilla/rust/wiki/Doc-using-rustdoc">wiki</a> makes some attempt at specifying conventions, but these need to be fleshed out and actually applied to the codebase.</p>
<p dir="auto">Right now, some doc-comments are written in the third-person indicative:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="pub fn map&lt;T, U&gt;(opt: &amp;Option&lt;T&gt;, f: fn(x: &amp;T) -&gt; U) -&gt; Option&lt;U&gt; {
    //! Maps a `some` value by reference from one type to another"><pre class="notranslate"><span class="pl-k">pub</span> <span class="pl-k">fn</span> map<span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">,</span> <span class="pl-smi">U</span><span class="pl-kos">&gt;</span><span class="pl-kos">(</span><span class="pl-s1">opt</span><span class="pl-kos">:</span> <span class="pl-c1">&amp;</span><span class="pl-smi">Option</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-s1">f</span><span class="pl-kos">:</span> <span class="pl-k">fn</span><span class="pl-kos">(</span><span class="pl-s1">x</span><span class="pl-kos">:</span> <span class="pl-c1">&amp;</span><span class="pl-smi">T</span><span class="pl-kos">)</span> -&gt; <span class="pl-smi">U</span><span class="pl-kos">)</span> -&gt; <span class="pl-smi">Option</span><span class="pl-kos">&lt;</span><span class="pl-smi">U</span><span class="pl-kos">&gt;</span> <span class="pl-kos">{</span>
    <span class="pl-c">//! Maps a `some` value by reference from one type to another</span></pre></div>
<p dir="auto">and some are written in the imperative:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="pub fn chain&lt;T, U&gt;(opt: Option&lt;T&gt;,
                   f: fn(t: T) -&gt; Option&lt;U&gt;) -&gt; Option&lt;U&gt; {
    /*!
     * Update an optional value by optionally running its content through a
     * function that returns an option.
     */"><pre class="notranslate"><span class="pl-k">pub</span> <span class="pl-k">fn</span> chain<span class="pl-kos">&lt;</span><span class="pl-smi">T</span><span class="pl-kos">,</span> <span class="pl-smi">U</span><span class="pl-kos">&gt;</span><span class="pl-kos">(</span><span class="pl-s1">opt</span><span class="pl-kos">:</span> <span class="pl-smi">Option</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-s1">f</span><span class="pl-kos">:</span> <span class="pl-k">fn</span><span class="pl-kos">(</span><span class="pl-s1">t</span><span class="pl-kos">:</span> <span class="pl-smi">T</span><span class="pl-kos">)</span> -&gt; <span class="pl-smi">Option</span><span class="pl-kos">&lt;</span><span class="pl-smi">U</span><span class="pl-kos">&gt;</span><span class="pl-kos">)</span> -&gt; <span class="pl-smi">Option</span><span class="pl-kos">&lt;</span><span class="pl-smi">U</span><span class="pl-kos">&gt;</span> <span class="pl-kos">{</span>
    <span class="pl-c">/*!</span>
<span class="pl-c">     * Update an optional value by optionally running its content through a</span>
<span class="pl-c">     * function that returns an option.</span>
<span class="pl-c">     */</span></pre></div>
<p dir="auto">These two examples illustrate another inconsistency: Some summaries (the first line of the comment) have no terminal punctuation, while others end with a period.</p>
<p dir="auto">One more thing that varies is the comment style itself. Some doc-comments look like</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="/*!
 * foo...
 * bar...
 * baz...
 */"><pre class="notranslate"><span class="pl-c">/*!</span>
<span class="pl-c"> * foo...</span>
<span class="pl-c"> * bar...</span>
<span class="pl-c"> * baz...</span>
<span class="pl-c"> */</span></pre></div>
<p dir="auto">while others look like</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="/*!
 foo...
 bar...
 baz...
 */"><pre class="notranslate"><span class="pl-c">/*!</span>
<span class="pl-c"> foo...</span>
<span class="pl-c"> bar...</span>
<span class="pl-c"> baz...</span>
<span class="pl-c"> */</span></pre></div>
<p dir="auto">Once these rules (and others) are codified, I'd be happy to start going through the doc-comments and updating them.</p>