rustc: doc comments

src/librustdoc/html/escape.rs

@@ -1,6 +1,6 @@
-//! HTML Escaping
+//! HTML escaping.
 //!
-//! This module contains one unit-struct which can be used to HTML-escape a
+//! This module contains one unit struct, which can be used to HTML-escape a
 //! string of text (for use in a format string).
 
 use std::fmt;

src/librustdoc/html/format.rs

@@ -54,13 +54,13 @@ pub struct Method<'a> {
     pub indent: usize,
 }
 
-/// Wrapper struct for emitting a where clause from Generics.
+/// Wrapper struct for emitting a where-clause from Generics.
 pub struct WhereClause<'a>{
-    /// The Generics from which to emit a where clause.
+    /// The Generics from which to emit a where-clause.
     pub gens: &'a clean::Generics,
     /// The number of spaces to indent each line with.
     pub indent: usize,
-    /// Whether the where clause needs to add a comma and newline after the last bound.
+    /// Whether the where-clause needs to add a comma and newline after the last bound.
     pub end_newline: bool,
 }
 

src/librustdoc/html/highlight.rs

@@ -124,7 +124,7 @@ trait Writer {
     /// Called at the end of a span of highlighted text.
     fn exit_span(&mut self) -> io::Result<()>;
 
-    /// Called for a span of text.  If the text should be highlighted differently from the
+    /// Called for a span of text. If the text should be highlighted differently from the
     /// surrounding text, then the `Class` argument will be a value other than `None`.
     ///
     /// The following sequences of callbacks are equivalent:

src/librustdoc/html/markdown.rs

@@ -1,8 +1,8 @@
-//! Markdown formatting for rustdoc
+//! Markdown formatting for rustdoc.
 //!
 //! This module implements markdown formatting through the pulldown-cmark
 //! rust-library. This module exposes all of the
-//! functionality through a unit-struct, `Markdown`, which has an implementation
+//! functionality through a unit struct, `Markdown`, which has an implementation
 //! of `fmt::Display`. Example usage:
 //!
 //! ```
@@ -139,7 +139,7 @@ thread_local!(pub static PLAYGROUND: RefCell<Option<(Option<String>, String)>> =
     RefCell::new(None)
 });
 
-/// Adds syntax highlighting and playground Run buttons to rust code blocks.
+/// Adds syntax highlighting and playground Run buttons to Rust code blocks.
 struct CodeBlocks<'a, I: Iterator<Item = Event<'a>>> {
     inner: I,
     check_error_codes: ErrorCodes,
@@ -277,7 +277,7 @@ impl<'a, I: Iterator<Item = Event<'a>>> Iterator for CodeBlocks<'a, I> {
     }
 }
 
-/// Make headings links with anchor ids and build up TOC.
+/// Make headings links with anchor IDs and build up TOC.
 struct LinkReplacer<'a, 'b, I: Iterator<Item = Event<'a>>> {
     inner: I,
     links: &'b [(String, String)],
@@ -310,7 +310,7 @@ impl<'a, 'b, I: Iterator<Item = Event<'a>>> Iterator for LinkReplacer<'a, 'b, I>
     }
 }
 
-/// Make headings links with anchor ids and build up TOC.
+/// Make headings links with anchor IDs and build up TOC.
 struct HeadingLinks<'a, 'b, 'ids, I: Iterator<Item = Event<'a>>> {
     inner: I,
     toc: Option<&'b mut TocBuilder>,

src/librustdoc/html/render.rs

@@ -1,4 +1,4 @@
-//! Rustdoc's HTML Rendering module
+//! Rustdoc's HTML rendering module.
 //!
 //! This modules contains the bulk of the logic necessary for rendering a
 //! rustdoc `clean::Crate` instance to a set of static HTML pages. This
@@ -163,7 +163,7 @@ impl SharedContext {
 }
 
 impl SharedContext {
-    /// Returns whether the `collapse-docs` pass was run on this crate.
+    /// Returns `true` if the `collapse-docs` pass was run on this crate.
     pub fn was_collapsed(&self) -> bool {
         self.passes.contains("collapse-docs")
     }
@@ -267,11 +267,11 @@ macro_rules! try_err {
 #[derive(Default)]
 pub struct Cache {
     /// Mapping of typaram ids to the name of the type parameter. This is used
-    /// when pretty-printing a type (so pretty printing doesn't have to
+    /// when pretty-printing a type (so pretty-printing doesn't have to
     /// painfully maintain a context like this)
     pub typarams: FxHashMap<DefId, String>,
 
-    /// Maps a type id to all known implementations for that type. This is only
+    /// Maps a type ID to all known implementations for that type. This is only
     /// recognized for intra-crate `ResolvedPath` types, and is used to print
     /// out extra documentation on the page of an enum/struct.
     ///
@@ -279,7 +279,7 @@ pub struct Cache {
     /// found on that implementation.
     pub impls: FxHashMap<DefId, Vec<Impl>>,
 
-    /// Maintains a mapping of local crate node ids to the fully qualified name
+    /// Maintains a mapping of local crate `NodeId`s to the fully qualified name
     /// and "short type description" of that node. This is used when generating
     /// URLs when a type is being linked to. External paths are not located in
     /// this map because the `External` type itself has all the information
@@ -290,7 +290,7 @@ pub struct Cache {
     /// generating explicit hyperlinks to other crates.
     pub external_paths: FxHashMap<DefId, (Vec<String>, ItemType)>,
 
-    /// Maps local def ids of exported types to fully qualified paths.
+    /// Maps local `DefId`s of exported types to fully qualified paths.
     /// Unlike 'paths', this mapping ignores any renames that occur
     /// due to 'use' statements.
     ///
@@ -692,7 +692,7 @@ pub fn run(mut krate: clean::Crate,
     cx.krate(krate)
 }
 
-/// Build the search index from the collected metadata
+/// Builds the search index from the collected metadata
 fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String {
     let mut nodeid_to_pathid = FxHashMap::default();
     let mut crate_items = Vec::with_capacity(cache.search_index.len());
@@ -2293,7 +2293,7 @@ impl Context {
 }
 
 impl<'a> Item<'a> {
-    /// Generate a url appropriate for an `href` attribute back to the source of
+    /// Generates a url appropriate for an `href` attribute back to the source of
     /// this item.
     ///
     /// The url generated, when clicked, will redirect the browser back to the

src/librustdoc/html/toc.rs

@@ -58,7 +58,7 @@ impl TocBuilder {
     }
 
 
-    /// Convert into a true `Toc` struct.
+    /// Converts into a true `Toc` struct.
     pub fn into_toc(mut self) -> Toc {
         // we know all levels are >= 1.
         self.fold_until(0);