refactor stack

src/parsers/mod.rs

@@ -158,9 +158,6 @@ impl<R: Read> BencodeParser<R> {
             self.iter += 1;
         }
 
-        // todo: if we exit the loop with a non default stack, that's an error
-        // (incomplete bencode value).
-
         Ok(())
     }
 

src/parsers/stack.rs

@@ -73,22 +73,37 @@ impl Display for Stack {
 }
 
 impl Stack {
+    /// It adds a new state to the stack.
     pub fn push(&mut self, item: State) {
         self.items.push(item);
     }
 
+    /// It returns and consume the stack top.
+    ///
+    /// It doesn't allow popping the initial state.
+    ///
+    /// # Panics
+    ///
+    /// Will panic is the stack state is the initial state.
     pub fn pop(&mut self) {
         self.guard_immutable_initial_state();
         self.items.pop();
     }
 
+    /// It swaps the stack top with the new item.
+    ///
+    /// It doesn't allow swapping the initial state.
+    ///
+    /// # Panics
+    ///
+    /// Will panic is the stack state is the initial state.
     pub fn swap_top(&mut self, new_item: State) {
         self.guard_immutable_initial_state();
         self.items.pop();
         self.push(new_item);
     }
 
-    /// It returns the top element on the stack without removing it.
+    /// It returns the top element on the stack without consuming it.
     ///
     /// # Panics
     ///