* lib/irb.rb, lib/irb/*: Documentation for IRB

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38515 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

8 files changed, 80 insertions, 10 deletions

diff --git a/lib/irb/ext/change-ws.rb b/lib/irb/ext/change-ws.rb
index a28754e378..ce921eb5e3 100644
--- a/lib/irb/ext/change-ws.rb
+++ b/lib/irb/ext/change-ws.rb
@@ -12,6 +12,7 @@
 module IRB # :nodoc:
   class Context
 
+    # Inherited from +TOPLEVEL_BINDING+.
     def home_workspace
       if defined? @home_workspace
 	@home_workspace
diff --git a/lib/irb/ext/history.rb b/lib/irb/ext/history.rb
index 4d036e7cf0..3239c57a6c 100644
--- a/lib/irb/ext/history.rb
+++ b/lib/irb/ext/history.rb
@@ -15,6 +15,7 @@ module IRB # :nodoc:
 
     NOPRINTING_IVARS.push "@eval_history_values"
 
+    # See #set_last_value
     alias _set_last_value set_last_value
 
     def set_last_value(value)
@@ -57,7 +58,7 @@ module IRB # :nodoc:
     end
   end
 
-  class History
+  class History # :nodoc:
     @RCS_ID='-$Id$-'
 
     def initialize(size = 16)
diff --git a/lib/irb/ext/loader.rb b/lib/irb/ext/loader.rb
index 2058a2fa29..6cdc8ec898 100644
--- a/lib/irb/ext/loader.rb
+++ b/lib/irb/ext/loader.rb
@@ -14,12 +14,16 @@ module IRB # :nodoc:
   # Raised in the event of an exception in a file loaded from an Irb session
   class LoadAbort < Exception;end
 
+  # Provides a few commands for loading files within an irb session.
+  #
+  # See ExtendCommandBundle for more information.
   module IrbLoader
     @RCS_ID='-$Id$-'
 
     alias ruby_load load
     alias ruby_require require
 
+    # Loads the given file similarly to Kernel#load
     def irb_load(fn, priv = nil)
       path = search_file_from_ruby_path(fn)
       raise LoadError, "No such file to load -- #{fn}" unless path
@@ -27,7 +31,7 @@ module IRB # :nodoc:
       load_file(path, priv)
     end
 
-    def search_file_from_ruby_path(fn)
+    def search_file_from_ruby_path(fn) # :nodoc:
       if /^#{Regexp.quote(File::Separator)}/ =~ fn
 	return fn if File.exist?(fn)
 	return nil
@@ -41,6 +45,9 @@ module IRB # :nodoc:
       return nil
     end
 
+    # Loads a given file in the current session and displays the source lines
+    #
+    # See Irb#suspend_input_method for more information.
     def source_file(path)
       irb.suspend_name(path, File.basename(path)) do
 	irb.suspend_input_method(FileInputMethod.new(path)) do
@@ -60,6 +67,9 @@ module IRB # :nodoc:
       end
     end
 
+    # Loads the given file in the current session's context and evaluates it.
+    #
+    # See Irb#suspend_input_method for more information.
     def load_file(path, priv = nil)
       irb.suspend_name(path, File.basename(path)) do
 
@@ -88,7 +98,7 @@ module IRB # :nodoc:
       end
     end
 
-    def old
+    def old # :nodoc:
       back_io = @io
       back_path = @irb_path
       back_name = @irb_name
diff --git a/lib/irb/ext/multi-irb.rb b/lib/irb/ext/multi-irb.rb
index 473a4361b7..e49a158fa3 100644
--- a/lib/irb/ext/multi-irb.rb
+++ b/lib/irb/ext/multi-irb.rb
@@ -12,44 +12,61 @@ IRB.fail CantShiftToMultiIrbMode unless defined?(Thread)
 require "thread"
 
 module IRB
-  # job management class
   class JobManager
     @RCS_ID='-$Id$-'
 
+    # Creates a new JobManager object
     def initialize
       # @jobs = [[thread, irb],...]
       @jobs = []
       @current_job = nil
     end
 
+    # The active irb session
     attr_accessor :current_job
 
+    # The total number of irb sessions, used to set +irb_name+ of the current
+    # Context.
     def n_jobs
       @jobs.size
     end
 
+    # Returns the thread for the given +key+ object, see #search for more
+    # information.
     def thread(key)
       th, = search(key)
       th
     end
 
+    # Returns the irb session for the given +key+ object, see #search for more
+    # information.
     def irb(key)
       _, irb = search(key)
       irb
     end
 
+    # Returns the top level thread.
     def main_thread
       @jobs[0][0]
     end
 
+    # Returns the top level irb session.
     def main_irb
       @jobs[0][1]
     end
 
+    # Add the given +irb+ session to the jobs Array.
     def insert(irb)
       @jobs.push [Thread.current, irb]
     end
 
+    # Changes the current active irb session to the given +key+ in the jobs
+    # Array.
+    #
+    # Raises an IrbAlreadyDead exception if the given +key+ is no longer alive.
+    #
+    # If the given irb session is already active, an IrbSwitchedToCurrentThread
+    # exception is raised.
     def switch(key)
       th, irb = search(key)
       IRB.fail IrbAlreadyDead unless th.alive?
@@ -60,6 +77,12 @@ module IRB
       @current_job = irb(Thread.current)
     end
 
+    # Terminates the irb sessions specified by the given +keys+.
+    #
+    # Raises an IrbAlreadyDead exception if one of the given +keys+ is already
+    # terminated.
+    #
+    # See Thread#exit for more information.
     def kill(*keys)
       for key in keys
 	th, _ = search(key)
@@ -68,6 +91,20 @@ module IRB
       end
     end
 
+    # Returns the associated job for the given +key+.
+    #
+    # If given an Integer, it will return the +key+ index for the jobs Array.
+    #
+    # When an instance of Irb is given, it will return the irb session
+    # associated with +key+.
+    #
+    # If given an instance of Thread, it will return the associated thread
+    # +key+ using Object#=== on the jobs Array.
+    #
+    # Otherwise returns the irb session with the same top-level binding as the
+    # given +key+.
+    #
+    # Raises a NoSuchJob exception if no job can be found with the given +key+.
     def search(key)
       job = case key
       when Integer
@@ -83,6 +120,7 @@ module IRB
       job
     end
 
+    # Deletes the job at the given +key+.
     def delete(key)
       case key
       when Integer
@@ -106,6 +144,7 @@ module IRB
       @jobs.push assoc
     end
 
+    # Outputs a list of jobs, see the irb command +irb_jobs+, or +jobs+.
     def inspect
       ary = []
       @jobs.each_index do
@@ -135,10 +174,12 @@ module IRB
 
   @JobManager = JobManager.new
 
+  # The current JobManager in the session
   def IRB.JobManager
     @JobManager
   end
 
+  # The current Context in this session
   def IRB.CurrentContext
     IRB.JobManager.irb(Thread.current).context
   end
diff --git a/lib/irb/ext/save-history.rb b/lib/irb/ext/save-history.rb
index f9c983ac11..3e0740d6fa 100644
--- a/lib/irb/ext/save-history.rb
+++ b/lib/irb/ext/save-history.rb
@@ -11,21 +11,24 @@
 require "readline"
 
 module IRB
-  module HistorySavingAbility
+  module HistorySavingAbility # :nodoc:
     @RCS_ID='-$Id$-'
   end
 
   class Context
-    def init_save_history
+    def init_save_history# :nodoc:
       unless (class<<@io;self;end).include?(HistorySavingAbility)
 	@io.extend(HistorySavingAbility)
       end
     end
 
+    # A copy of the default <code>IRB.conf[:SAVE_HISTORY]</code>
     def save_history
       IRB.conf[:SAVE_HISTORY]
     end
 
+    # Sets <code>IRB.conf[:SAVE_HISTORY]</code> to the given +val+ and calls
+    # #init_save_history with this context.
     def save_history=(val)
       IRB.conf[:SAVE_HISTORY] = val
       if val
@@ -35,16 +38,18 @@ module IRB
       end
     end
 
+    # A copy of the default <code>IRB.conf[:HISTORY_FILE]</code>
     def history_file
       IRB.conf[:HISTORY_FILE]
     end
 
+    # Set <code>IRB.conf[:HISTORY_FILE]</code> to the given +hist+.
     def history_file=(hist)
       IRB.conf[:HISTORY_FILE] = hist
     end
   end
 
-  module HistorySavingAbility
+  module HistorySavingAbility # :nodoc:
     include Readline
 
 #     def HistorySavingAbility.create_finalizer
diff --git a/lib/irb/ext/tracer.rb b/lib/irb/ext/tracer.rb
index 46a9d53a2e..8c9083dbad 100644
--- a/lib/irb/ext/tracer.rb
+++ b/lib/irb/ext/tracer.rb
@@ -23,9 +23,16 @@ module IRB
   end
 
   class Context
+    # Whether Tracer is used when evaluating statements in this context.
+    #
+    # See +lib/tracer.rb+ for more information.
     attr_reader :use_tracer
     alias use_tracer? use_tracer
 
+    # Sets whether or not to use the Tracer library when evaluating statements
+    # in this context.
+    #
+    # See +lib/tracer.rb+ for more information.
     def use_tracer=(opt)
       if opt
 	Tracer.set_get_line_procs(@irb_path) {
@@ -41,6 +48,10 @@ module IRB
 
   class WorkSpace
     alias __evaluate__ evaluate
+    # Evaluate the context of this workspace and use the Tracer library to
+    # output the exact lines of code are being executed in chronological order.
+    #
+    # See +lib/tracer.rb+ for more information.
     def evaluate(context, statements, file = nil, line = nil)
       if context.use_tracer? && file != nil && line != nil
 	Tracer.on
diff --git a/lib/irb/ext/use-loader.rb b/lib/irb/ext/use-loader.rb
index 913a64116f..4e98f5b7a2 100644
--- a/lib/irb/ext/use-loader.rb
+++ b/lib/irb/ext/use-loader.rb
@@ -18,16 +18,16 @@ class Object
 end
 
 module IRB
-  # :stopdoc:
   module ExtendCommandBundle
+    # Loads the given file similarly to Kernel#load, see IrbLoader#irb_load
     def irb_load(*opts, &b)
       ExtendCommand::Load.execute(irb_context, *opts, &b)
     end
+    # Loads the given file similarly to Kernel#require
     def irb_require(*opts, &b)
       ExtendCommand::Require.execute(irb_context, *opts, &b)
     end
   end
-  # :startdoc:
 
   class Context
 
diff --git a/lib/irb/ext/workspaces.rb b/lib/irb/ext/workspaces.rb
index 1232fee84f..641befbdf3 100644
--- a/lib/irb/ext/workspaces.rb
+++ b/lib/irb/ext/workspaces.rb
@@ -12,11 +12,12 @@
 module IRB # :nodoc:
   class Context
 
+    # Size of the current WorkSpace stack
     def irb_level
       workspace_stack.size
     end
 
-    # Workspaces in the current stack
+    # WorkSpaces in the current stack
     def workspaces
       if defined? @workspaces
 	@workspaces