history.rb in irb-1.1.0.pre.4

- old
+ new

@@ -29,21 +29,27 @@
 
       @last_value
     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+.
     #
     # Returns +no+ of history items if greater than 0.
     #
     # 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
           @eval_history_values.size(no)
         else
@@ -57,24 +63,55 @@
       end
       @eval_history = no
     end
   end
 
-  class History # :nodoc:
+  # 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)
+    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
           @contents.find{|no, val| no == idx}[1]
         else
@@ -83,17 +120,17 @@
       rescue NameError
         nil
       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
 
       unless (last = @contents.pop)[1].equal?(self)