IRB: Document command evaluation history.

1 files changed, 45 insertions, 8 deletions

diff --git a/lib/irb/ext/history.rb b/lib/irb/ext/history.rb
index 43c3e4dbf3..30e3fb901f 100644
--- a/lib/irb/ext/history.rb
+++ b/lib/irb/ext/history.rb
@@ -31,9 +31,12 @@ module IRB # :nodoc:
     end
 
     remove_method :eval_history= if method_defined?(:eval_history=)
-    # The command result history limit.
+    # The command result history limit. This method is not available until
+    # #eval_history= was called with non-nil value (directly or via
+    # setting <code>IRB.conf[:EVAL_HISTORY]</code> in <code>.irbrc</code>).
     attr_reader :eval_history
-    # Sets command result history limit.
+    # Sets command result history limit. Default value is set from
+    # <code>IRB.conf[:EVAL_HISTORY]</code>.
     #
     # +no+ is an Integer or +nil+.
     #
@@ -42,6 +45,9 @@ module IRB # :nodoc:
     # If +no+ is 0, the number of history items is unlimited.
     #
     # If +no+ is +nil+, execution result history isn't used (default).
+    #
+    # History values are available via <code>__</code> variable, see
+    # IRB::History.
     def eval_history=(no)
       if no
         if defined?(@eval_history) && @eval_history
@@ -59,20 +65,51 @@ module IRB # :nodoc:
     end
   end
 
-  class History # :nodoc:
-
-    def initialize(size = 16)
+  # Represents history of results of previously evaluated commands.
+  #
+  # Available via <code>__</code> variable, only if <code>IRB.conf[:EVAL_HISTORY]</code>
+  # or <code>IRB::CurrentContext().eval_history</code> is non-nil integer value
+  # (by default it is +nil+).
+  #
+  # Example (in `irb`):
+  #
+  #    # Initialize history
+  #    IRB::CurrentContext().eval_history = 10
+  #    # => 10
+  #
+  #    # Perform some commands...
+  #    1 + 2
+  #    # => 3
+  #    puts 'x'
+  #    # x
+  #    # => nil
+  #    raise RuntimeError
+  #    # ...error raised
+  #
+  #    # Inspect history (format is "<item number> <evaluated value>":
+  #    __
+  #    # => 1 10
+  #    # 2 3
+  #    # 3 nil
+  #
+  #    __[1]
+  #    # => 10
+  #
+  class History
+
+    def initialize(size = 16)  # :nodoc:
       @size = size
       @contents = []
     end
 
-    def size(size)
+    def size(size) # :nodoc:
       if size != 0 && size < @size
         @contents = @contents[@size - size .. @size]
       end
       @size = size
     end
 
+    # Get one item of the content (both positive and negative indexes work).
     def [](idx)
       begin
         if idx >= 0
@@ -85,14 +122,14 @@ module IRB # :nodoc:
       end
     end
 
-    def push(no, val)
+    def push(no, val)  # :nodoc:
       @contents.push [no, val]
       @contents.shift if @size != 0 && @contents.size > @size
     end
 
     alias real_inspect inspect
 
-    def inspect
+    def inspect  # :nodoc:
       if @contents.empty?
         return real_inspect
       end