Rollup merge of rust-lang#59273 - llogiq:hir-docs, r=matthewjasper

Mark-Simulacrum · web-flow · commit bd6a70def0ae · 2019-03-22T12:52:42.000Z
some small HIR doc improvements
diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs
@@ -815,6 +815,9 @@ pub struct MacroDef {
     pub legacy: bool,
 }
 
+/// A block of statements `{ .. }`, which may have a label (in this case the
+/// `targeted_by_break` field will be `true`) and may be `unsafe` by means of
+/// the `rules` being anything but `DefaultBlock`.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug, HashStable)]
 pub struct Block {
     /// Statements in a block.
@@ -1177,6 +1180,7 @@ impl fmt::Debug for Stmt {
     }
 }
 
+/// The contents of a statement.
 #[derive(Clone, RustcEncodable, RustcDecodable, HashStable)]
 pub enum StmtKind {
     /// A local (`let`) binding.
@@ -1207,21 +1211,28 @@ impl StmtKind {
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug, HashStable)]
 pub struct Local {
     pub pat: P<Pat>,
+    /// Type annotation, if any (otherwise the type will be inferred).
     pub ty: Option<P<Ty>>,
     /// Initializer expression to set the value, if any.
     pub init: Option<P<Expr>>,
     pub hir_id: HirId,
     pub span: Span,
     pub attrs: ThinVec<Attribute>,
+    /// Can be `ForLoopDesugar` if the `let` statement is part of a `for` loop
+    /// desugaring. Otherwise will be `Normal`.
     pub source: LocalSource,
 }
 
-/// Represents a single arm of a `match` expression.
+/// Represents a single arm of a `match` expression, e.g.
+/// `<pats> (if <guard>) => <body>`.
 #[derive(Clone, RustcEncodable, RustcDecodable, Debug, HashStable)]
 pub struct Arm {
     pub attrs: HirVec<Attribute>,
+    /// Multiple patterns can be combined with `|`
     pub pats: HirVec<P<Pat>>,
+    /// Optional guard clause.
     pub guard: Option<Guard>,
+    /// The expression the arm evaluates to if this arm matches.
     pub body: P<Expr>,
 }
 
