From 100c9ab9eeec24d6be474b72605f643c454cbee6 Mon Sep 17 00:00:00 2001
From: Ryan Fitzgerald <rwfitzge@gmail.com>
Date: Mon, 5 Sep 2011 13:52:49 -0700
Subject: [PATCH] add documentation for History

---
 lib/pry/history.rb   | 29 +++++++++++++++++++++++------
 lib/pry/pry_class.rb |  2 +-
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/lib/pry/history.rb b/lib/pry/history.rb
index 49022b08..439bc289 100644
--- a/lib/pry/history.rb
+++ b/lib/pry/history.rb
@@ -1,28 +1,39 @@
 class Pry
+  # The History class is responsible for maintaining the user's input history, both
+  # internally and within Readline::HISTORY.
   class History
     def initialize
       @history = []
-      @first_new_line = 0 # TODO: rename this
+      @saved_lines = 0
     end
 
+    # Loads a file's contents into the input history.
+    # @param [String] filename
+    # @return [Integer] The number of lines loaded
     def load(filename)
       File.foreach(filename) do |line|
         Readline::HISTORY << line.chomp
         @history << line.chomp
       end
-      @first_new_line = @history.length
+      @saved_lines = @history.length
     end
 
+    # Appends input history from this session to a file.
+    # @param [String] filename
+    # @return [Integer] The number of lines saved
     def save(filename)
-      history_to_save = @history[@first_new_line..-1]
+      history_to_save = @history[@saved_lines..-1]
       File.open(filename, 'a') do |f|
         history_to_save.each { |ln| f.puts ln }
       end
-      @first_new_line = @history.length
+      @saved_lines = @history.length
+      history_to_save.length
     end
 
+    # Adds a line to the input history, ignoring blank and duplicate lines.
+    # @param [String] line
+    # @return [String] The same line that was passed in
     def push(line)
-      line = line.to_s
       unless line.empty? || (@history.last && line.strip == @history.last.strip)
         Readline::HISTORY << line
         @history << line
@@ -31,12 +42,18 @@ class Pry
     end
     alias << push
 
+    # Clears all history. Anything the user entered before this point won't be
+    # saved, but anything they put in afterwards will still be appended to the
+    # history file on exit.
     def clear
       Readline::HISTORY.shift until Readline::HISTORY.empty?
       @history = []
-      @first_new_line = 0
+      @saved_lines = 0
     end
 
+    # Returns an Array containing all stored history.
+    # @return [Array<String>] An Array containing all lines of history loaded
+    #   or entered by the user in the current session.
     def to_a
       @history.dup
     end
diff --git a/lib/pry/pry_class.rb b/lib/pry/pry_class.rb
index 37f606a9..6e89d453 100644
--- a/lib/pry/pry_class.rb
+++ b/lib/pry/pry_class.rb
@@ -38,7 +38,7 @@ class Pry
     # @return [OpenStruct] Return Pry's config object.
     attr_accessor :config
 
-    # @return [History] TODO: put something here
+    # @return [History] Return Pry's line history object.
     attr_accessor :history
 
     # @return [Boolean] Whether Pry was activated from the command line.