rustc: doc comments

src/librustdoc/clean/cfg.rs

@@ -1,4 +1,4 @@
-//! Representation of a `#[doc(cfg(...))]` attribute.
+//! The representation of a `#[doc(cfg(...))]` attribute.
 
 // FIXME: Once the portability lint RFC is implemented (see tracking issue #41619),
 // switch to use those structures instead.
@@ -24,7 +24,7 @@ pub enum Cfg {
     False,
     /// A generic configuration option, e.g., `test` or `target_os = "linux"`.
     Cfg(Symbol, Option<Symbol>),
-    /// Negate a configuration requirement, i.e., `not(x)`.
+    /// Negates a configuration requirement, i.e., `not(x)`.
     Not(Box<Cfg>),
     /// Union of a list of configuration requirements, i.e., `any(...)`.
     Any(Vec<Cfg>),

src/librustdoc/clean/mod.rs

@@ -685,7 +685,7 @@ impl AttributesExt for [ast::Attribute] {
 }
 
 pub trait NestedAttributesExt {
-    /// Returns whether the attribute list contains a specific `Word`
+    /// Returns `true` if the attribute list contains a specific `Word`
     fn has_word(self, word: &str) -> bool;
 }
 
@@ -937,7 +937,7 @@ impl Attributes {
         }
     }
 
-    /// Get links as a vector
+    /// Gets links as a vector
     ///
     /// Cache must be populated before call
     pub fn links(&self, krate: &CrateNum) -> Vec<(String, String)> {
@@ -2147,12 +2147,12 @@ pub struct PolyTrait {
 /// it does not preserve mutability or boxes.
 #[derive(Clone, RustcEncodable, RustcDecodable, PartialEq, Eq, Debug, Hash)]
 pub enum Type {
-    /// structs/enums/traits (most that'd be an hir::TyKind::Path)
+    /// Structs/enums/traits (most that'd be an `hir::TyKind::Path`).
     ResolvedPath {
         path: Path,
         typarams: Option<Vec<GenericBound>>,
         did: DefId,
-        /// true if is a `T::Name` path for associated types
+        /// `true` if is a `T::Name` path for associated types.
         is_generic: bool,
     },
     /// For parameterized types, so the consumer of the JSON don't go
@@ -3955,7 +3955,7 @@ impl Clean<Deprecation> for attr::Deprecation {
     }
 }
 
-/// An equality constraint on an associated type, e.g., `A=Bar` in `Foo<A=Bar>`
+/// An equality constraint on an associated type, e.g., `A = Bar` in `Foo<A = Bar>`
 #[derive(Clone, PartialEq, Eq, RustcDecodable, RustcEncodable, Debug, Hash)]
 pub struct TypeBinding {
     pub name: String,

src/librustdoc/clean/simplify.rs

@@ -1,11 +1,11 @@
-//! Simplification of where clauses and parameter bounds into a prettier and
+//! Simplification of where-clauses and parameter bounds into a prettier and
 //! more canonical form.
 //!
 //! Currently all cross-crate-inlined function use `rustc::ty` to reconstruct
 //! the AST (e.g., see all of `clean::inline`), but this is not always a
-//! non-lossy transformation. The current format of storage for where clauses
+//! non-lossy transformation. The current format of storage for where-clauses
 //! for functions and such is simply a list of predicates. One example of this
-//! is that the AST predicate of: `where T: Trait<Foo=Bar>` is encoded as:
+//! is that the AST predicate of: `where T: Trait<Foo = Bar>` is encoded as:
 //! `where T: Trait, <T as Trait>::Foo = Bar`.
 //!
 //! This module attempts to reconstruct the original where and/or parameter

src/librustdoc/config.rs

@@ -150,9 +150,9 @@ pub struct RenderOptions {
     pub playground_url: Option<String>,
     /// Whether to sort modules alphabetically on a module page instead of using declaration order.
     /// `true` by default.
-    ///
-    /// FIXME(misdreavus): the flag name is `--sort-modules-by-appearance` but the meaning is
-    /// inverted once read
+    //
+    // FIXME(misdreavus): the flag name is `--sort-modules-by-appearance` but the meaning is
+    // inverted once read.
     pub sort_modules_alphabetically: bool,
     /// List of themes to extend the docs with. Original argument name is included to assist in
     /// displaying errors if it fails a theme check.
@@ -165,9 +165,9 @@ pub struct RenderOptions {
     pub resource_suffix: String,
     /// Whether to run the static CSS/JavaScript through a minifier when outputting them. `true` by
     /// default.
-    ///
-    /// FIXME(misdreavus): the flag name is `--disable-minification` but the meaning is inverted
-    /// once read
+    //
+    // FIXME(misdreavus): the flag name is `--disable-minification` but the meaning is inverted
+    // once read.
     pub enable_minification: bool,
     /// Whether to create an index page in the root of the output directory. If this is true but
     /// `enable_index_page` is None, generate a static listing of crates instead.
@@ -484,7 +484,7 @@ impl Options {
         })
     }
 
-    /// Returns whether the file given as `self.input` is a Markdown file.
+    /// Returns `true` if the file given as `self.input` is a Markdown file.
     pub fn markdown_input(&self) -> bool {
         self.input.extension()
             .map_or(false, |e| e == "md" || e == "markdown")

src/librustdoc/core.rs

@@ -63,7 +63,7 @@ pub struct DocContext<'a, 'tcx: 'a, 'rcx: 'a> {
 
     /// Table type parameter definition -> substituted type
     pub ty_substs: RefCell<FxHashMap<Def, clean::Type>>,
-    /// Table node id of lifetime parameter definition -> substituted lifetime
+    /// Table `NodeId` of lifetime parameter definition -> substituted lifetime
     pub lt_substs: RefCell<FxHashMap<DefId, clean::Lifetime>>,
     /// Table DefId of `impl Trait` in argument position -> bounds
     pub impl_trait_bounds: RefCell<FxHashMap<DefId, Vec<clean::GenericBound>>>,

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);

src/librustdoc/markdown.rs

@@ -127,7 +127,7 @@ pub fn render(input: PathBuf, options: RenderOptions, diag: &errors::Handler) ->
     }
 }
 
-/// Run any tests/code examples in the markdown file `input`.
+/// Runs any tests/code examples in the markdown file `input`.
 pub fn test(mut options: Options, diag: &errors::Handler) -> isize {
     let input_str = match load_string(&options.input, diag) {
         Ok(s) => s,

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -59,7 +59,7 @@ impl<'a, 'tcx, 'rcx> LinkCollector<'a, 'tcx, 'rcx> {
         }
     }
 
-    /// Resolve a given string as a path, along with whether or not it is
+    /// Resolves a given string as a path, along with whether or not it is
     /// in the value namespace. Also returns an optional URL fragment in the case
     /// of variants and methods.
     fn resolve(&self,
@@ -422,7 +422,7 @@ impl<'a, 'tcx, 'rcx> DocFolder for LinkCollector<'a, 'tcx, 'rcx> {
     }
 }
 
-/// Resolve a string as a macro.
+/// Resolves a string as a macro.
 fn macro_resolve(cx: &DocContext, path_str: &str) -> Option<Def> {
     use syntax::ext::base::{MacroKind, SyntaxExtension};
     let segment = ast::PathSegment::from_ident(Ident::from_str(path_str));

src/librustdoc/passes/mod.rs

@@ -403,7 +403,7 @@ pub fn look_for_tests<'a, 'tcx: 'a, 'rcx: 'a>(
     }
 }
 
-/// Return a span encompassing all the given attributes.
+/// Returns a span encompassing all the given attributes.
 crate fn span_of_attrs(attrs: &clean::Attributes) -> Span {
     if attrs.doc_strings.is_empty() {
         return DUMMY_SP;

src/librustdoc/visit_ast.rs

@@ -259,7 +259,7 @@ impl<'a, 'tcx, 'rcx> RustdocVisitor<'a, 'tcx, 'rcx> {
     /// Cross-crate inlining occurs later on during crate cleaning
     /// and follows different rules.
     ///
-    /// Returns true if the target has been inlined.
+    /// Returns `true` if the target has been inlined.
     fn maybe_inline_local(&mut self,
                           id: ast::NodeId,
                           def: Def,