* lib/irb*: merge doc from doc/irb/ird.rd and improve overall

documentation of IRB
* doc/irb/irb.rd: remove stale documentation


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

lib/irb/ext/change-ws.rb

@@ -9,7 +9,7 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
   class Context
 
     def home_workspace
@@ -20,6 +20,13 @@ module IRB
       end
     end
 
+    # Changes the current workspace to given object or binding.
+    #
+    # If the optional argument is omitted, the workspace will be
+    # #home_workspace which is inherited from +TOPLEVEL_BINDING+ or the main
+    # object, <code>IRB.conf[:MAIN_CONTEXT]</code> when irb was initialized.
+    #
+    # See IRB::WorkSpace.new for more information.
     def change_workspace(*_main)
       if _main.empty?
 	@workspace = home_workspace

lib/irb/ext/history.rb

@@ -9,7 +9,7 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
 
   class Context
 
@@ -29,7 +29,17 @@ module IRB
       @last_value
     end
 
+    # The command result history limit.
     attr_reader :eval_history
+    # Sets command result history limit.
+    #
+    # +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).
     def eval_history=(no)
       if no
 	if defined?(@eval_history) && @eval_history

lib/irb/ext/loader.rb

@@ -10,7 +10,8 @@
 #
 
 
-module IRB
+module IRB # :nodoc:
+  # Raised in the event of an exception in a file loaded from an Irb session
   class LoadAbort < Exception;end
 
   module IrbLoader

lib/irb/ext/math-mode.rb

@@ -12,9 +12,20 @@ require "mathn"
 
 module IRB
   class Context
+    # Returns whether bc mode is enabled.
+    #
+    # See #math_mode=
     attr_reader :math_mode
+    # Alias for #math_mode
     alias math? math_mode
 
+    # Sets bc mode, which loads +lib/mathn.rb+ so fractions or matrix are
+    # available.
+    #
+    # Also available as the +-m+ command line option.
+    #
+    # See IRB@Command+line+options and the unix manpage <code>bc(1)</code> for
+    # more information.
     def math_mode=(opt)
       if @math_mode == true && opt == false
 	IRB.fail CantReturnToNormalMode

lib/irb/ext/multi-irb.rb

@@ -143,7 +143,10 @@ module IRB
     IRB.JobManager.irb(Thread.current).context
   end
 
-  # invoke multi-irb
+  # Creates a new IRB session, see Irb.new.
+  #
+  # The optional +file+ argument is given to Context.new, along with the
+  # workspace created with the remaining arguments, see WorkSpace.new
   def IRB.irb(file = nil, *main)
     workspace = WorkSpace.new(*main)
     parent_thread = Thread.current

lib/irb/ext/use-loader.rb

@@ -18,6 +18,7 @@ class Object
 end
 
 module IRB
+  # :stopdoc:
   module ExtendCommandBundle
     def irb_load(*opts, &b)
       ExtendCommand::Load.execute(irb_context, *opts, &b)
@@ -26,17 +27,25 @@ module IRB
       ExtendCommand::Require.execute(irb_context, *opts, &b)
     end
   end
+  # :startdoc:
 
   class Context
 
     IRB.conf[:USE_LOADER] = false
 
+    # Returns whether +irb+'s own file reader method is used by
+    # +load+/+require+ or not.
+    #
+    # This mode is globally affected (irb-wide).
     def use_loader
       IRB.conf[:USE_LOADER]
     end
 
     alias use_loader? use_loader
 
+    # Sets IRB.conf[:USE_LOADER]
+    #
+    # See #use_loader for more information.
     def use_loader=(opt)
 
       if IRB.conf[:USE_LOADER] != opt

lib/irb/ext/workspaces.rb

@@ -9,13 +9,14 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
   class Context
 
     def irb_level
       workspace_stack.size
     end
 
+    # Workspaces in the current stack
     def workspaces
       if defined? @workspaces
 	@workspaces
@@ -24,6 +25,11 @@ module IRB
       end
     end
 
+    # Creates a new workspace with the given object or binding, and appends it
+    # onto the current #workspaces stack.
+    #
+    # See IRB::Context#change_workspace and IRB::WorkSpace.new for more
+    # information.
     def push_workspace(*_main)
       if _main.empty?
 	if workspaces.empty?
@@ -43,6 +49,10 @@ module IRB
       end
     end
 
+    # Removes the last element from the current #workspaces stack and returns
+    # it, or +nil+ if the current workspace stack is empty.
+    #
+    # Also, see #push_workspace.
     def pop_workspace
       if workspaces.empty?
 	print "workspace stack empty\n"