Auto merge of #33752 - mrhota:internal_docs, r=steveklabnik

Internal docs

This PR is a rebase of #30621. That PR can be closed.

CC @ticki @Aatch @cyplo

src/librustc/hir/map/blocks.rs

@@ -133,7 +133,13 @@ struct ClosureParts<'a> {
 
 impl<'a> ClosureParts<'a> {
     fn new(d: &'a FnDecl, b: &'a Block, id: NodeId, s: Span, attrs: &'a [Attribute]) -> Self {
-        ClosureParts { decl: d, body: b, id: id, span: s, attrs: attrs }
+        ClosureParts {
+            decl: d,
+            body: b,
+            id: id,
+            span: s,
+            attrs: attrs,
+        }
     }
 }
 

src/librustc/hir/map/collector.rs

@@ -19,10 +19,13 @@ use std::iter::repeat;
 use syntax::ast::{NodeId, CRATE_NODE_ID};
 use syntax::codemap::Span;
 
-/// A Visitor that walks over the HIR and collects Node's into a HIR map.
+/// A Visitor that walks over the HIR and collects Nodes into a HIR map
 pub struct NodeCollector<'ast> {
+    /// The crate
     pub krate: &'ast Crate,
+    /// The node map
     pub map: Vec<MapEntry<'ast>>,
+    /// The parent of this node
     pub parent_node: NodeId,
 }
 

src/librustc/hir/map/definitions.rs

@@ -15,6 +15,7 @@ use syntax::ast;
 use syntax::parse::token::InternedString;
 use util::nodemap::NodeMap;
 
+/// The definition table containing node definitions
 #[derive(Clone)]
 pub struct Definitions {
     data: Vec<DefData>,
@@ -139,31 +140,47 @@ pub struct InlinedRootPath {
 pub enum DefPathData {
     // Root: these should only be used for the root nodes, because
     // they are treated specially by the `def_path` function.
+    /// The crate root (marker)
     CrateRoot,
+    /// An inlined root
     InlinedRoot(Box<InlinedRootPath>),
 
     // Catch-all for random DefId things like DUMMY_NODE_ID
     Misc,
 
     // Different kinds of items and item-like things:
+    /// An impl
     Impl,
-    TypeNs(ast::Name), // something in the type NS
-    ValueNs(ast::Name), // something in the value NS
+    /// Something in the type NS
+    TypeNs(ast::Name),
+    /// Something in the value NS
+    ValueNs(ast::Name),
+    /// A module declaration
     Module(ast::Name),
+    /// A macro rule
     MacroDef(ast::Name),
+    /// A closure expression
     ClosureExpr,
 
     // Subportions of items
+    /// A type parameter (generic parameter)
     TypeParam(ast::Name),
+    /// A lifetime definition
     LifetimeDef(ast::Name),
+    /// A variant of a enum
     EnumVariant(ast::Name),
+    /// A struct field
     Field(ast::Name),
-    StructCtor, // implicit ctor for a tuple-like struct
-    Initializer, // initializer for a const
-    Binding(ast::Name), // pattern binding
+    /// Implicit ctor for a tuple-like struct
+    StructCtor,
+    /// Initializer for a const
+    Initializer,
+    /// Pattern binding
+    Binding(ast::Name),
 }
 
 impl Definitions {
+    /// Create new empty definition map.
     pub fn new() -> Definitions {
         Definitions {
             data: vec![],
@@ -172,6 +189,7 @@ impl Definitions {
         }
     }
 
+    /// Get the number of definitions.
     pub fn len(&self) -> usize {
         self.data.len()
     }
@@ -214,6 +232,7 @@ impl Definitions {
         }
     }
 
+    /// Add a definition with a parent definition.
     pub fn create_def_with_parent(&mut self,
                                   parent: Option<DefIndex>,
                                   node_id: ast::NodeId,

src/librustc_back/sha2.rs

@@ -25,11 +25,10 @@ fn write_u32_be(dst: &mut[u8], input: u32) {
 
 /// Read the value of a vector of bytes as a u32 value in big-endian format.
 fn read_u32_be(input: &[u8]) -> u32 {
-    return
-        (input[0] as u32) << 24 |
+    (input[0] as u32) << 24 |
         (input[1] as u32) << 16 |
         (input[2] as u32) << 8 |
-        (input[3] as u32);
+        (input[3] as u32)
 }
 
 /// Read a vector of bytes into a vector of u32s. The values are read in big-endian format.
@@ -50,7 +49,7 @@ trait ToBits: Sized {
 
 impl ToBits for u64 {
     fn to_bits(self) -> (u64, u64) {
-        return (self >> 61, self << 3);
+        (self >> 61, self << 3)
     }
 }
 
@@ -64,7 +63,7 @@ fn add_bytes_to_bits(bits: u64, bytes: u64) -> u64 {
     }
 
     match bits.checked_add(new_low_bits) {
-        Some(x) => return x,
+        Some(x) => x,
         None => panic!("numeric overflow occurred.")
     }
 }
@@ -113,10 +112,10 @@ struct FixedBuffer64 {
 impl FixedBuffer64 {
     /// Create a new FixedBuffer64
     fn new() -> FixedBuffer64 {
-        return FixedBuffer64 {
+        FixedBuffer64 {
             buffer: [0; 64],
             buffer_idx: 0
-        };
+        }
     }
 }
 
@@ -175,13 +174,13 @@ impl FixedBuffer for FixedBuffer64 {
 
     fn next<'s>(&'s mut self, len: usize) -> &'s mut [u8] {
         self.buffer_idx += len;
-        return &mut self.buffer[self.buffer_idx - len..self.buffer_idx];
+        &mut self.buffer[self.buffer_idx - len..self.buffer_idx]
     }
 
     fn full_buffer<'s>(&'s mut self) -> &'s [u8] {
         assert!(self.buffer_idx == 64);
         self.buffer_idx = 0;
-        return &self.buffer[..64];
+        &self.buffer[..64]
     }
 
     fn position(&self) -> usize { self.buffer_idx }
@@ -278,7 +277,7 @@ struct Engine256State {
 
 impl Engine256State {
     fn new(h: &[u32; 8]) -> Engine256State {
-        return Engine256State {
+        Engine256State {
             h0: h[0],
             h1: h[1],
             h2: h[2],
@@ -287,7 +286,7 @@ impl Engine256State {
             h5: h[5],
             h6: h[6],
             h7: h[7]
-        };
+        }
     }
 
     fn reset(&mut self, h: &[u32; 8]) {
@@ -433,7 +432,7 @@ struct Engine256 {
 
 impl Engine256 {
     fn new(h: &[u32; 8]) -> Engine256 {
-        return Engine256 {
+        Engine256 {
             length_bits: 0,
             buffer: FixedBuffer64::new(),
             state: Engine256State::new(h),
@@ -457,17 +456,15 @@ impl Engine256 {
     }
 
     fn finish(&mut self) {
-        if self.finished {
-            return;
+        if !self.finished {
+            let self_state = &mut self.state;
+            self.buffer.standard_padding(8, |input: &[u8]| { self_state.process_block(input) });
+            write_u32_be(self.buffer.next(4), (self.length_bits >> 32) as u32 );
+            write_u32_be(self.buffer.next(4), self.length_bits as u32);
+            self_state.process_block(self.buffer.full_buffer());
+
+            self.finished = true;
         }
-
-        let self_state = &mut self.state;
-        self.buffer.standard_padding(8, |input: &[u8]| { self_state.process_block(input) });
-        write_u32_be(self.buffer.next(4), (self.length_bits >> 32) as u32 );
-        write_u32_be(self.buffer.next(4), self.length_bits as u32);
-        self_state.process_block(self.buffer.full_buffer());
-
-        self.finished = true;
     }
 }