Auto merge of #58341 - alexreg:cosmetic-2-doc-comments, r=steveklabnik

Cosmetic improvements to doc comments

This has been factored out from https://github.com/rust-lang/rust/pull/58036 to only include changes to documentation comments (throughout the rustc codebase).

r? @steveklabnik

Once you're happy with this, maybe we could get it through with r=1, so it doesn't constantly get invalidated? (I'm not sure this will be an issue, but just in case...) Anyway, thanks for your advice so far!

diff --cc src/liballoc/macros.rs
Simple merge

diff --cc src/libcore/convert.rs
Simple merge

diff --cc src/libcore/macros.rs
index 6b5fe84ff61dfa4cb7dec2ce4e10339726deffed,2a9cb75df2ce4fd75a03f4aca7cfd7bd85a3998d..2eb506cedd4f83a02e951d1e9ad93f783bb4fe78
--- 1/src/libcore/macros.rs
--- 2/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@@ -1,7 -1,6 +1,7 @@@
- /// Entry point of thread panic, for details, see std::macros
+ /// Entry point of thread panic. For details, see `std::macros`.
  #[macro_export]
 -#[allow_internal_unstable]
 +#[cfg_attr(not(stage0), allow_internal_unstable(core_panic, __rust_unstable_column))]
 +#[cfg_attr(stage0, allow_internal_unstable)]
  #[stable(feature = "core", since = "1.6.0")]
  macro_rules! panic {
      () => (

diff --cc src/libcore/num/mod.rs
Simple merge

diff --cc src/libgraphviz/lib.rs
Simple merge

diff --cc src/libproc_macro/lib.rs
Simple merge

diff --cc src/librustc/hir/lowering.rs
Simple merge

diff --cc src/librustc/hir/map/mod.rs
Simple merge

diff --cc src/librustc/infer/mod.rs
Simple merge

diff --cc src/librustc/middle/stability.rs
Simple merge

diff --cc src/librustc/mir/interpret/mod.rs
Simple merge

diff --cc src/librustc/ty/fold.rs
Simple merge

diff --cc src/librustc_apfloat/lib.rs
Simple merge

diff --cc src/librustc_codegen_ssa/back/write.rs
Simple merge

diff --cc src/librustc_codegen_ssa/base.rs
index 988e3bbd71d8acf3167b35b4c40044c6ce009d64,ecac82db94798de9244d814c956a7ade4f207dbb..7aa75f139d2ae4456aef58df025fa4428ff883c6
--- 1/src/librustc_codegen_ssa/base.rs
--- 2/src/librustc_codegen_ssa/base.rs
+++ b/src/librustc_codegen_ssa/base.rs
@@@ -7,13 -7,13 +7,13 @@@
  //!
  //! Hopefully useful general knowledge about codegen:
  //!
- //!   * There's no way to find out the Ty type of a Value.  Doing so
- //!     would be "trying to get the eggs out of an omelette" (credit:
- //!     pcwalton).  You can, instead, find out its llvm::Type by calling val_ty,
- //!     but one llvm::Type corresponds to many `Ty`s; for instance, tup(int, int,
- //!     int) and rec(x=int, y=int, z=int) will have the same llvm::Type.
+ //! * There's no way to find out the `Ty` type of a Value. Doing so
+ //!   would be "trying to get the eggs out of an omelette" (credit:
+ //!   pcwalton). You can, instead, find out its `llvm::Type` by calling `val_ty`,
+ //!   but one `llvm::Type` corresponds to many `Ty`s; for instance, `tup(int, int,
+ //!   int)` and `rec(x=int, y=int, z=int)` will have the same `llvm::Type`.
  
 -use {ModuleCodegen, ModuleKind, CachedModuleCodegen};
 +use crate::{ModuleCodegen, ModuleKind, CachedModuleCodegen};
  
  use rustc::dep_graph::cgu_reuse_tracker::CguReuse;
  use rustc::hir::def_id::{CrateNum, DefId, LOCAL_CRATE};

diff --cc src/librustc_codegen_ssa/lib.rs
Simple merge

diff --cc src/librustc_codegen_ssa/mir/block.rs
Simple merge

diff --cc src/librustc_codegen_ssa/mir/mod.rs
Simple merge

diff --cc src/librustc_codegen_ssa/mir/place.rs
Simple merge

diff --cc src/librustc_codegen_ssa/traits/type_.rs
Simple merge

diff --cc src/librustc_driver/lib.rs
Simple merge

diff --cc src/librustc_errors/lib.rs
Simple merge

diff --cc src/librustc_metadata/creader.rs
Simple merge

diff --cc src/librustc_mir/borrow_check/error_reporting.rs
Simple merge

diff --cc src/librustc_mir/borrow_check/nll/region_infer/error_reporting/region_name.rs
Simple merge

diff --cc src/librustc_mir/borrow_check/nll/universal_regions.rs
Simple merge

diff --cc src/librustc_mir/build/mod.rs
Simple merge

diff --cc src/librustc_mir/interpret/intrinsics.rs
Simple merge

diff --cc src/librustc_mir/interpret/place.rs
Simple merge

diff --cc src/librustc_mir/interpret/visitor.rs
index 4ff5cde08d08694cf1aa287e954a02d34dcd4944,24fbb56dc52e4cd7eba6e1dedd4ea697a9615d3c..e2abf2ffc849c265fc98c62b2e1afbe4739fb905
--- 1/src/librustc_mir/interpret/visitor.rs
--- 2/src/librustc_mir/interpret/visitor.rs
+++ b/src/librustc_mir/interpret/visitor.rs
@@@ -131,11 -131,11 +131,11 @@@ macro_rules! make_value_visitor 
              type V: Value<'a, 'mir, 'tcx, M>;
  
              /// The visitor must have an `EvalContext` in it.
 -            fn ecx(&$($mutability)* self)
 -                -> &$($mutability)* EvalContext<'a, 'mir, 'tcx, M>;
 +            fn ecx(&$($mutability)? self)
 +                -> &$($mutability)? EvalContext<'a, 'mir, 'tcx, M>;
  
              // Recursive actions, ready to be overloaded.
-             /// Visit the given value, dispatching as appropriate to more specialized visitors.
+             /// Visits the given value, dispatching as appropriate to more specialized visitors.
              #[inline(always)]
              fn visit_value(&mut self, v: Self::V) -> EvalResult<'tcx>
              {

diff --cc src/librustc_mir/transform/qualify_consts.rs
Simple merge

diff --cc src/librustc_mir/transform/qualify_min_const_fn.rs
Simple merge

diff --cc src/librustc_plugin/lib.rs
Simple merge

diff --cc src/librustc_plugin/registry.rs
Simple merge

diff --cc src/librustc_privacy/lib.rs
Simple merge

diff --cc src/librustc_resolve/lib.rs
Simple merge

diff --cc src/librustc_save_analysis/lib.rs
Simple merge

diff --cc src/librustc_typeck/astconv.rs
Simple merge

diff --cc src/librustc_typeck/check/cast.rs
Simple merge

diff --cc src/librustc_typeck/check/closure.rs
Simple merge

diff --cc src/librustc_typeck/check/coercion.rs
index 8a91e425db7bf40d194f2994bbafc60e81a4c307,332f97a9ae718f0e2ff16ac017d1ab64b2deed51..90071e3f3634ad084b37e481f7b9a9725fcf9426
--- 1/src/librustc_typeck/check/coercion.rs
--- 2/src/librustc_typeck/check/coercion.rs
+++ b/src/librustc_typeck/check/coercion.rs
@@@ -44,13 -44,13 +44,13 @@@
  //! *unsubstituted* type when deciding whether to auto-borrow, but the
  //! *substituted* type when considering the bounds and so forth. But most
  //! of our methods don't give access to the unsubstituted type, and
- //! rightly so because they'd be error-prone.  So maybe the thing to do is
+ //! rightly so because they'd be error-prone. So maybe the thing to do is
  //! to actually determine the kind of coercions that should occur
- //! separately and pass them in.  Or maybe it's ok as is.  Anyway, it's
- //! sort of a minor point so I've opted to leave it for later---after all
+ //! separately and pass them in. Or maybe it's ok as is. Anyway, it's
+ //! sort of a minor point so I've opted to leave it for later -- after all,
  //! we may want to adjust precisely when coercions occur.
  
 -use check::{FnCtxt, Needs};
 +use crate::check::{FnCtxt, Needs};
  use errors::DiagnosticBuilder;
  use rustc::hir;
  use rustc::hir::def_id::DefId;

diff --cc src/librustc_typeck/check/compare_method.rs
Simple merge

diff --cc src/librustc_typeck/check/dropck.rs
Simple merge

diff --cc src/librustc_typeck/check/intrinsic.rs
Simple merge

diff --cc src/librustc_typeck/check/method/mod.rs
Simple merge

diff --cc src/librustc_typeck/check/method/probe.rs
Simple merge

diff --cc src/librustc_typeck/check/method/suggest.rs
Simple merge

diff --cc src/librustc_typeck/check/mod.rs
Simple merge

diff --cc src/librustc_typeck/check/regionck.rs
Simple merge

diff --cc src/librustc_typeck/check/wfcheck.rs
Simple merge

diff --cc src/librustc_typeck/check_unused.rs
Simple merge

diff --cc src/librustc_typeck/coherence/mod.rs
Simple merge

diff --cc src/librustc_typeck/collect.rs
Simple merge

diff --cc src/librustc_typeck/constrained_type_params.rs
Simple merge

diff --cc src/librustc_typeck/impl_wf_check.rs
Simple merge

diff --cc src/librustc_typeck/lib.rs
Simple merge

diff --cc src/librustc_typeck/outlives/implicit_infer.rs
Simple merge

diff --cc src/librustdoc/clean/mod.rs
Simple merge

diff --cc src/librustdoc/html/format.rs
index c03e679bc519480283a73ed4270253cebd6b2003,830e1402b96dcda8198ac94da9214582544cbd1f..35555f61bd150980491510c37aa8f8820aaa2a40
--- 1/src/librustdoc/html/format.rs
--- 2/src/librustdoc/html/format.rs
+++ b/src/librustdoc/html/format.rs
@@@ -53,13 -52,11 +53,13 @@@ pub struct Function<'a> 
      pub name_len: usize,
      /// The number of spaces to indent each successive line with, if line-wrapping is necessary.
      pub indent: usize,
 +    /// Whether the function is async or not.
 +    pub asyncness: hir::IsAsync,
  }
  
- /// 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,

diff --cc src/librustdoc/html/render.rs
Simple merge

diff --cc src/librustdoc/passes/mod.rs
Simple merge

diff --cc src/librustdoc/visit_ast.rs
Simple merge

diff --cc src/libserialize/hex.rs
Simple merge

diff --cc src/libserialize/json.rs
index 5b3444b9f456f33d94ac14f6db30bb8faa26d144,a34714c32808e0e7695786abf26d3edf1b0bd90e..a4fd28845120542adbf78a469fb520f922b5f7e6
--- 1/src/libserialize/json.rs
--- 2/src/libserialize/json.rs
+++ b/src/libserialize/json.rs
@@@ -1010,15 -1011,15 +1010,15 @@@ impl Encodable for Json 
      }
  }
  
- /// Create an `AsJson` wrapper which can be used to print a value as JSON
+ /// Creates an `AsJson` wrapper which can be used to print a value as JSON
  /// on-the-fly via `write!`
 -pub fn as_json<T>(t: &T) -> AsJson<T> {
 +pub fn as_json<T>(t: &T) -> AsJson<'_, T> {
      AsJson { inner: t }
  }
  
- /// Create an `AsPrettyJson` wrapper which can be used to print a value as JSON
+ /// Creates an `AsPrettyJson` wrapper which can be used to print a value as JSON
  /// on-the-fly via `write!`
 -pub fn as_pretty_json<T>(t: &T) -> AsPrettyJson<T> {
 +pub fn as_pretty_json<T>(t: &T) -> AsPrettyJson<'_, T> {
      AsPrettyJson { inner: t, indent: None }
  }
  
@@@ -1319,9 -1320,9 +1319,9 @@@ impl Stack 
          true
      }
  
-     /// Returns true if the bottom-most elements of this stack are the same as
+     /// Returns `true` if the bottom-most elements of this stack are the same as
      /// the ones passed as parameter.
 -    pub fn starts_with(&self, rhs: &[StackElement]) -> bool {
 +    pub fn starts_with(&self, rhs: &[StackElement<'_>]) -> bool {
          if self.stack.len() < rhs.len() { return false; }
          for (i, r) in rhs.iter().enumerate() {
              if self.get(i) != *r { return false; }
@@@ -1329,9 -1330,9 +1329,9 @@@
          true
      }
  
-     /// Returns true if the top-most elements of this stack are the same as
+     /// Returns `true` if the top-most elements of this stack are the same as
      /// the ones passed as parameter.
 -    pub fn ends_with(&self, rhs: &[StackElement]) -> bool {
 +    pub fn ends_with(&self, rhs: &[StackElement<'_>]) -> bool {
          if self.stack.len() < rhs.len() { return false; }
          let offset = self.stack.len() - rhs.len();
          for (i, r) in rhs.iter().enumerate() {

diff --cc src/libserialize/serialize.rs
Simple merge

diff --cc src/libstd/macros.rs
Simple merge

diff --cc src/libstd/net/ip.rs
Simple merge

diff --cc src/libstd/sync/mpsc/mod.rs
Simple merge

diff --cc src/libstd/sync/mpsc/select.rs
Simple merge

diff --cc src/libsyntax/ext/base.rs
Simple merge

diff --cc src/libsyntax/ext/expand.rs
Simple merge

diff --cc src/libsyntax/ext/tt/macro_rules.rs
Simple merge

diff --cc src/libsyntax/feature_gate.rs
Simple merge

diff --cc src/libsyntax_ext/format.rs
Simple merge

diff --cc src/libsyntax_pos/hygiene.rs
Simple merge

diff --cc src/libsyntax_pos/lib.rs
index 042005ea538899eca3b795e57b915c4d12f4ca2b,bffc686b8169883108421dfaa0e72711890a9e31..f4771a52034d8de5700b1fad1ce9a32f80b4d0db
--- 1/src/libsyntax_pos/lib.rs
--- 2/src/libsyntax_pos/lib.rs
+++ b/src/libsyntax_pos/lib.rs
@@@ -383,16 -382,12 +383,16 @@@ impl Span 
          self.ctxt().outer().expn_info().map(source_callee)
      }
  
-     /// Check if a span is "internal" to a macro in which `#[unstable]`
+     /// Checks if a span is "internal" to a macro in which `#[unstable]`
      /// items can be used (that is, a macro marked with
      /// `#[allow_internal_unstable]`).
 -    pub fn allows_unstable(&self) -> bool {
 +    pub fn allows_unstable(&self, feature: &str) -> bool {
          match self.ctxt().outer().expn_info() {
 -            Some(info) => info.allow_internal_unstable,
 +            Some(info) => info
 +                .allow_internal_unstable
 +                .map_or(false, |features| features.iter().any(|&f|
 +                    f == feature || f == "allow_internal_unstable_backcompat_hack"
 +                )),
              None => false,
          }
      }

diff --cc src/libterm/lib.rs
Simple merge

diff --cc src/libterm/terminfo/mod.rs
Simple merge

diff --cc src/libterm/terminfo/parm.rs
index 4e81b8a7f28a6b892c604679ac3d8f6aab0a0214,e55307dcdf09bc7c137e753138c1e05cec1f78fb..28229bd87b0a5ebc632b977f3f24130c023e5140
--- 1/src/libterm/terminfo/parm.rs
--- 2/src/libterm/terminfo/parm.rs
+++ b/src/libterm/terminfo/parm.rs
@@@ -46,21 -46,17 +46,21 @@@ pub struct Variables 
  }
  
  impl Variables {
-     /// Return a new zero-initialized Variables
+     /// Returns a new zero-initialized Variables
      pub fn new() -> Variables {
          Variables {
 -            sta: [Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0)],
 -            dyn: [Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 -                  Number(0), Number(0), Number(0), Number(0), Number(0)],
 +            sta_va: [
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0)
 +            ],
 +            dyn_va: [
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0), Number(0), Number(0),
 +                Number(0), Number(0), Number(0), Number(0), Number(0)
 +            ],
          }
      }
  }

diff --cc src/libterm/terminfo/parser/compiled.rs
Simple merge

diff --cc src/libterm/win.rs
index 1051ddf1986f474ee8a8e61b584a71fdcad5b779,a09a5f6da21dc8975e5759d2d7fd339aa93a2342..6d42b01337ed531bd36e2c323a5effcbd9a7a548
--- 1/src/libterm/win.rs
--- 2/src/libterm/win.rs
+++ b/src/libterm/win.rs
@@@ -7,11 -7,11 +7,11 @@@ extern crate libc
  use std::io;
  use std::io::prelude::*;
  
 -use Attr;
 -use color;
 -use Terminal;
 +use crate::Attr;
 +use crate::color;
 +use crate::Terminal;
  
- /// A Terminal implementation which uses the Win32 Console API.
+ /// A Terminal implementation that uses the Win32 Console API.
  pub struct WinConsole<T> {
      buf: T,
      def_foreground: color::Color,