rustc: doc comments

4 files changed, 52 insertions, 51 deletions

diff --git a/src/librustc/ty/query/job.rs b/src/librustc/ty/query/job.rs
index 0793366e6d4..16b4af53594 100644
--- a/src/librustc/ty/query/job.rs
+++ b/src/librustc/ty/query/job.rs
@@ -31,37 +31,38 @@ use {
     rustc_data_structures::stable_hasher::{StableHasherResult, StableHasher, HashStable},
 };
 
-/// Indicates the state of a query for a given key in a query map
+/// Indicates the state of a query for a given key in a query map.
 pub(super) enum QueryResult<'tcx> {
-    /// An already executing query. The query job can be used to await for its completion
+    /// An already executing query. The query job can be used to await for its completion.
     Started(Lrc<QueryJob<'tcx>>),
 
-    /// The query panicked. Queries trying to wait on this will raise a fatal error / silently panic
+    /// The query panicked. Queries trying to wait on this will raise a fatal error or
+    /// silently panic.
     Poisoned,
 }
 
-/// A span and a query key
+/// Represents a span and a query key.
 #[derive(Clone, Debug)]
 pub struct QueryInfo<'tcx> {
-    /// The span for a reason this query was required
+    /// The span corresponding to the reason for which this query was required.
     pub span: Span,
     pub query: Query<'tcx>,
 }
 
-/// A object representing an active query job.
+/// Representss an object representing an active query job.
 pub struct QueryJob<'tcx> {
     pub info: QueryInfo<'tcx>,
 
     /// The parent query job which created this job and is implicitly waiting on it.
     pub parent: Option<Lrc<QueryJob<'tcx>>>,
 
-    /// The latch which is used to wait on this job
+    /// The latch that is used to wait on this job.
     #[cfg(parallel_compiler)]
     latch: QueryLatch<'tcx>,
 }
 
 impl<'tcx> QueryJob<'tcx> {
-    /// Creates a new query job
+    /// Creates a new query job.
     pub fn new(info: QueryInfo<'tcx>, parent: Option<Lrc<QueryJob<'tcx>>>) -> Self {
         QueryJob {
             info,
@@ -230,7 +231,7 @@ impl<'tcx> QueryLatch<'tcx> {
         }
     }
 
-    /// Remove a single waiter from the list of waiters.
+    /// Removes a single waiter from the list of waiters.
     /// This is used to break query cycles.
     fn extract_waiter(
         &self,
diff --git a/src/librustc/ty/query/mod.rs b/src/librustc/ty/query/mod.rs
index d002b99f385..67a5c7d6c9a 100644
--- a/src/librustc/ty/query/mod.rs
+++ b/src/librustc/ty/query/mod.rs
@@ -102,12 +102,12 @@ define_queries! { <'tcx>
         /// Records the type of every item.
         [] fn type_of: TypeOfItem(DefId) -> Ty<'tcx>,
 
-        /// Maps from the def-id of an item (trait/struct/enum/fn) to its
+        /// Maps from the `DefId` of an item (trait/struct/enum/fn) to its
         /// associated generics.
         [] fn generics_of: GenericsOfItem(DefId) -> &'tcx ty::Generics,
 
-        /// Maps from the def-id of an item (trait/struct/enum/fn) to the
-        /// predicates (where clauses) that must be proven true in order
+        /// Maps from the `DefId` of an item (trait/struct/enum/fn) to the
+        /// predicates (where-clauses) that must be proven true in order
         /// to reference it. This is almost always the "predicates query"
         /// that you want.
         ///
@@ -123,8 +123,8 @@ define_queries! { <'tcx>
         /// user.)
         [] fn predicates_of: PredicatesOfItem(DefId) -> Lrc<ty::GenericPredicates<'tcx>>,
 
-        /// Maps from the def-id of an item (trait/struct/enum/fn) to the
-        /// predicates (where clauses) directly defined on it. This is
+        /// Maps from the `DefId` of an item (trait/struct/enum/fn) to the
+        /// predicates (where-clauses) directly defined on it. This is
         /// equal to the `explicit_predicates_of` predicates plus the
         /// `inferred_outlives_of` predicates.
         [] fn predicates_defined_on: PredicatesDefinedOnItem(DefId)
@@ -138,7 +138,7 @@ define_queries! { <'tcx>
         /// Foo<'a, T> { x: &'a T }`, this would return `T: 'a`).
         [] fn inferred_outlives_of: InferredOutlivesOf(DefId) -> Lrc<Vec<ty::Predicate<'tcx>>>,
 
-        /// Maps from the def-id of a trait to the list of
+        /// Maps from the `DefId` of a trait to the list of
         /// super-predicates. This is a subset of the full list of
         /// predicates. We store these in a separate map because we must
         /// evaluate them even during type conversion, often before the
@@ -216,7 +216,7 @@ define_queries! { <'tcx>
     },
 
     Codegen {
-        /// Set of all the def-ids in this crate that have MIR associated with
+        /// Set of all the `DefId`s in this crate that have MIR associated with
         /// them. This includes all the body owners, but also things like struct
         /// constructors.
         [] fn mir_keys: mir_keys(CrateNum) -> Lrc<DefIdSet>,
@@ -226,11 +226,11 @@ define_queries! { <'tcx>
         /// the value isn't known except to the pass itself.
         [] fn mir_const_qualif: MirConstQualif(DefId) -> (u8, Lrc<BitSet<mir::Local>>),
 
-        /// Fetch the MIR for a given def-id right after it's built - this includes
+        /// Fetch the MIR for a given `DefId` right after it's built - this includes
         /// unreachable code.
         [] fn mir_built: MirBuilt(DefId) -> &'tcx Steal<mir::Mir<'tcx>>,
 
-        /// Fetch the MIR for a given def-id up till the point where it is
+        /// Fetch the MIR for a given `DefId` up till the point where it is
         /// ready for const evaluation.
         ///
         /// See the README for the `mir` module for details.
@@ -244,7 +244,7 @@ define_queries! { <'tcx>
     },
 
     TypeChecking {
-        /// The result of unsafety-checking this def-id.
+        /// The result of unsafety-checking this `DefId`.
         [] fn unsafety_check_result: UnsafetyCheckResult(DefId) -> mir::UnsafetyCheckResult,
 
         /// HACK: when evaluated, this reports a "unsafe derive on repr(packed)" error
@@ -307,13 +307,13 @@ define_queries! { <'tcx>
     TypeChecking {
         /// Gets a complete map from all types to their inherent impls.
         /// Not meant to be used directly outside of coherence.
-        /// (Defined only for LOCAL_CRATE)
+        /// (Defined only for `LOCAL_CRATE`.)
         [] fn crate_inherent_impls: crate_inherent_impls_dep_node(CrateNum)
             -> Lrc<CrateInherentImpls>,
 
-        /// Checks all types in the krate for overlap in their inherent impls. Reports errors.
+        /// Checks all types in the crate for overlap in their inherent impls. Reports errors.
         /// Not meant to be used directly outside of coherence.
-        /// (Defined only for LOCAL_CRATE)
+        /// (Defined only for `LOCAL_CRATE`.)
         [] fn crate_inherent_impls_overlap_check: inherent_impls_overlap_check_dep_node(CrateNum)
             -> (),
     },
@@ -321,9 +321,9 @@ define_queries! { <'tcx>
     Other {
         /// Evaluate a constant without running sanity checks
         ///
-        /// DO NOT USE THIS outside const eval. Const eval uses this to break query cycles during
-        /// validation. Please add a comment to every use site explaining why using `const_eval`
-        /// isn't sufficient
+        /// **Do not use this** outside const eval. Const eval uses this to break query cycles
+        /// during validation. Please add a comment to every use site explaining why using
+        /// `const_eval` isn't sufficient
         [] fn const_eval_raw: const_eval_raw_dep_node(ty::ParamEnvAnd<'tcx, GlobalId<'tcx>>)
             -> ConstEvalRawResult<'tcx>,
 
@@ -344,7 +344,7 @@ define_queries! { <'tcx>
     Other {
         [] fn reachable_set: reachability_dep_node(CrateNum) -> ReachableSet,
 
-        /// Per-body `region::ScopeTree`. The `DefId` should be the owner-def-id for the body;
+        /// Per-body `region::ScopeTree`. The `DefId` should be the owner `DefId` for the body;
         /// in the case of closures, this will be redirected to the enclosing function.
         [] fn region_scope_tree: RegionScopeTree(DefId) -> Lrc<region::ScopeTree>,
 
@@ -398,7 +398,7 @@ define_queries! { <'tcx>
             -> Lrc<specialization_graph::Graph>,
         [] fn is_object_safe: ObjectSafety(DefId) -> bool,
 
-        /// Get the ParameterEnvironment for a given item; this environment
+        /// Gets the ParameterEnvironment for a given item; this environment
         /// will be in "user-facing" mode, meaning that it is suitabe for
         /// type-checking etc, and it does not normalize specializable
         /// associated types. This is almost always what you want,
@@ -485,7 +485,7 @@ define_queries! { <'tcx>
 
         [] fn foreign_modules: ForeignModules(CrateNum) -> Lrc<Vec<ForeignModule>>,
 
-        /// Identifies the entry-point (e.g. the `main` function) for a given
+        /// Identifies the entry-point (e.g., the `main` function) for a given
         /// crate, returning `None` if there is no entry point (such as for library crates).
         [] fn entry_fn: EntryFn(CrateNum) -> Option<(DefId, EntryFnType)>,
         [] fn plugin_registrar_fn: PluginRegistrarFn(CrateNum) -> Option<DefId>,
diff --git a/src/librustc/ty/query/on_disk_cache.rs b/src/librustc/ty/query/on_disk_cache.rs
index 9c9bc0f6aa1..f948abc7f6f 100644
--- a/src/librustc/ty/query/on_disk_cache.rs
+++ b/src/librustc/ty/query/on_disk_cache.rs
@@ -103,7 +103,7 @@ impl AbsoluteBytePos {
 }
 
 impl<'sess> OnDiskCache<'sess> {
-    /// Create a new OnDiskCache instance from the serialized data in `data`.
+    /// Creates a new OnDiskCache instance from the serialized data in `data`.
     pub fn new(sess: &'sess Session, data: Vec<u8>, start_pos: usize) -> OnDiskCache<'sess> {
         debug_assert!(sess.opts.incremental.is_some());
 
@@ -325,7 +325,7 @@ impl<'sess> OnDiskCache<'sess> {
         })
     }
 
-    /// Load a diagnostic emitted during the previous compilation session.
+    /// Loads a diagnostic emitted during the previous compilation session.
     pub fn load_diagnostics<'a, 'tcx>(&self,
                                       tcx: TyCtxt<'a, 'tcx, 'tcx>,
                                       dep_node_index: SerializedDepNodeIndex)
@@ -339,7 +339,7 @@ impl<'sess> OnDiskCache<'sess> {
         diagnostics.unwrap_or_default()
     }
 
-    /// Store a diagnostic emitted during the current compilation session.
+    /// Stores a diagnostic emitted during the current compilation session.
     /// Anything stored like this will be available via `load_diagnostics` in
     /// the next compilation session.
     #[inline(never)]
@@ -353,7 +353,7 @@ impl<'sess> OnDiskCache<'sess> {
     }
 
     /// Returns the cached query result if there is something in the cache for
-    /// the given SerializedDepNodeIndex. Otherwise returns None.
+    /// the given `SerializedDepNodeIndex`; otherwise returns `None`.
     pub fn try_load_query_result<'tcx, T>(&self,
                                           tcx: TyCtxt<'_, 'tcx, 'tcx>,
                                           dep_node_index: SerializedDepNodeIndex)
@@ -366,7 +366,7 @@ impl<'sess> OnDiskCache<'sess> {
                           "query result")
     }
 
-    /// Store a diagnostic emitted during computation of an anonymous query.
+    /// Stores a diagnostic emitted during computation of an anonymous query.
     /// Since many anonymous queries can share the same `DepNode`, we aggregate
     /// them -- as opposed to regular queries where we assume that there is a
     /// 1:1 relationship between query-key and `DepNode`.
diff --git a/src/librustc/ty/query/plumbing.rs b/src/librustc/ty/query/plumbing.rs
index f63fbd79825..9b2a70a6a6d 100644
--- a/src/librustc/ty/query/plumbing.rs
+++ b/src/librustc/ty/query/plumbing.rs
@@ -1,6 +1,6 @@
-//! The implementation of the query system itself. Defines the macros
-//! that generate the actual methods on tcx which find and execute the
-//! provider, manage the caches, and so forth.
+//! The implementation of the query system itself. This defines the macros that
+//! generate the actual methods on tcx which find and execute the provider,
+//! manage the caches, and so forth.
 
 use crate::dep_graph::{DepNodeIndex, DepNode, DepKind, SerializedDepNodeIndex};
 use crate::errors::DiagnosticBuilder;
@@ -1017,8 +1017,8 @@ macro_rules! define_queries_inner {
         }
 
         impl<'a, $tcx, 'lcx> TyCtxt<'a, $tcx, 'lcx> {
-            /// Return a transparent wrapper for `TyCtxt` which ensures queries
-            /// are executed instead of returing their result
+            /// Returns a transparent wrapper for `TyCtxt`, which ensures queries
+            /// are executed instead of just returing their results.
             #[inline(always)]
             pub fn ensure(self) -> TyCtxtEnsure<'a, $tcx, 'lcx> {
                 TyCtxtEnsure {
@@ -1026,7 +1026,7 @@ macro_rules! define_queries_inner {
                 }
             }
 
-            /// Return a transparent wrapper for `TyCtxt` which uses
+            /// Returns a transparent wrapper for `TyCtxt` which uses
             /// `span` as the location of queries performed through it.
             #[inline(always)]
             pub fn at(self, span: Span) -> TyCtxtAt<'a, $tcx, 'lcx> {
@@ -1067,7 +1067,7 @@ macro_rules! define_queries_struct {
     (tcx: $tcx:tt,
      input: ($(([$($modifiers:tt)*] [$($attr:tt)*] [$name:ident]))*)) => {
         pub struct Queries<$tcx> {
-            /// This provides access to the incr. comp. on-disk cache for query results.
+            /// This provides access to the incrimental comilation on-disk cache for query results.
             /// Do not access this directly. It is only meant to be used by
             /// `DepGraph::try_mark_green()` and the query infrastructure.
             pub(crate) on_disk_cache: OnDiskCache<'tcx>,
@@ -1123,22 +1123,22 @@ macro_rules! define_provider_struct {
 ///
 /// Now, if force_from_dep_node() would always fail, it would be pretty useless.
 /// Fortunately, we can use some contextual information that will allow us to
-/// reconstruct query-keys for certain kinds of DepNodes. In particular, we
-/// enforce by construction that the GUID/fingerprint of certain DepNodes is a
-/// valid DefPathHash. Since we also always build a huge table that maps every
-/// DefPathHash in the current codebase to the corresponding DefId, we have
+/// reconstruct query-keys for certain kinds of `DepNode`s. In particular, we
+/// enforce by construction that the GUID/fingerprint of certain `DepNode`s is a
+/// valid `DefPathHash`. Since we also always build a huge table that maps every
+/// `DefPathHash` in the current codebase to the corresponding `DefId`, we have
 /// everything we need to re-run the query.
 ///
 /// Take the `mir_validated` query as an example. Like many other queries, it
-/// just has a single parameter: the DefId of the item it will compute the
-/// validated MIR for. Now, when we call `force_from_dep_node()` on a dep-node
-/// with kind `MirValidated`, we know that the GUID/fingerprint of the dep-node
-/// is actually a DefPathHash, and can therefore just look up the corresponding
-/// DefId in `tcx.def_path_hash_to_def_id`.
+/// just has a single parameter: the `DefId` of the item it will compute the
+/// validated MIR for. Now, when we call `force_from_dep_node()` on a `DepNode`
+/// with kind `MirValidated`, we know that the GUID/fingerprint of the `DepNode`
+/// is actually a `DefPathHash`, and can therefore just look up the corresponding
+/// `DefId` in `tcx.def_path_hash_to_def_id`.
 ///
 /// When you implement a new query, it will likely have a corresponding new
-/// DepKind, and you'll have to support it here in `force_from_dep_node()`. As
-/// a rule of thumb, if your query takes a DefId or DefIndex as sole parameter,
+/// `DepKind`, and you'll have to support it here in `force_from_dep_node()`. As
+/// a rule of thumb, if your query takes a `DefId` or `DefIndex` as sole parameter,
 /// then `force_from_dep_node()` should not fail for it. Otherwise, you can just
 /// add it to the "We don't have enough information to reconstruct..." group in
 /// the match below.