* 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

27 files changed, 165 insertions, 20 deletions

diff --git a/lib/irb/cmd/chws.rb b/lib/irb/cmd/chws.rb
index 65c977016b..1889e75d5e 100644
--- a/lib/irb/cmd/chws.rb
+++ b/lib/irb/cmd/chws.rb
@@ -12,6 +12,7 @@
 require "irb/cmd/nop.rb"
 require "irb/ext/change-ws.rb"
 
+# :stopdoc:
 module IRB
   module ExtendCommand
 
@@ -29,4 +30,4 @@ module IRB
     end
   end
 end
-
+# :startdoc:
diff --git a/lib/irb/cmd/fork.rb b/lib/irb/cmd/fork.rb
index a3531d4299..fbe5126c85 100644
--- a/lib/irb/cmd/fork.rb
+++ b/lib/irb/cmd/fork.rb
@@ -11,7 +11,7 @@
 
 @RCS_ID='-$Id$-'
 
-
+# :stopdoc:
 module IRB
   module ExtendCommand
     class Fork<Nop
@@ -34,5 +34,6 @@ module IRB
     end
   end
 end
+# :startdoc:
 
 
diff --git a/lib/irb/cmd/help.rb b/lib/irb/cmd/help.rb
index 67cf89990b..76e299fc20 100644
--- a/lib/irb/cmd/help.rb
+++ b/lib/irb/cmd/help.rb
@@ -12,6 +12,7 @@ require 'rdoc/ri/driver'
 
 require "irb/cmd/nop.rb"
 
+# :stopdoc:
 module IRB
   module ExtendCommand
     class Help<Nop
@@ -37,3 +38,4 @@ module IRB
     end
   end
 end
+# :startdoc:
diff --git a/lib/irb/cmd/load.rb b/lib/irb/cmd/load.rb
index 2a6de21ed7..6c9e9f67ce 100644
--- a/lib/irb/cmd/load.rb
+++ b/lib/irb/cmd/load.rb
@@ -12,6 +12,7 @@
 require "irb/cmd/nop.rb"
 require "irb/ext/loader"
 
+# :stopdoc:
 module IRB
   module ExtendCommand
     class Load<Nop
@@ -64,3 +65,4 @@ module IRB
   end
 
 end
+# :startdoc:
diff --git a/lib/irb/cmd/nop.rb b/lib/irb/cmd/nop.rb
index 2b028975c8..7bd443121e 100644
--- a/lib/irb/cmd/nop.rb
+++ b/lib/irb/cmd/nop.rb
@@ -8,6 +8,7 @@
 #
 #
 #
+# :stopdoc:
 module IRB
   module ExtendCommand
     class Nop
@@ -35,4 +36,4 @@ module IRB
     end
   end
 end
-
+# :startdoc:
diff --git a/lib/irb/cmd/pushws.rb b/lib/irb/cmd/pushws.rb
index 5fd567731c..cee8538e3e 100644
--- a/lib/irb/cmd/pushws.rb
+++ b/lib/irb/cmd/pushws.rb
@@ -12,6 +12,7 @@
 require "irb/cmd/nop.rb"
 require "irb/ext/workspaces.rb"
 
+# :stopdoc:
 module IRB
   module ExtendCommand
     class Workspaces<Nop
@@ -35,4 +36,5 @@ module IRB
     end
   end
 end
+# :startdoc:
 
diff --git a/lib/irb/cmd/subirb.rb b/lib/irb/cmd/subirb.rb
index 4d54a72b6f..7363d64769 100644
--- a/lib/irb/cmd/subirb.rb
+++ b/lib/irb/cmd/subirb.rb
@@ -11,6 +11,7 @@
 require "irb/cmd/nop.rb"
 require "irb/ext/multi-irb"
 
+# :stopdoc:
 module IRB
   module ExtendCommand
     class IrbCommand<Nop
@@ -38,3 +39,4 @@ module IRB
     end
   end
 end
+# :startdoc:
diff --git a/lib/irb/context.rb b/lib/irb/context.rb
index 61b519170d..0da8395640 100644
--- a/lib/irb/context.rb
+++ b/lib/irb/context.rb
@@ -13,12 +13,13 @@ require "irb/inspector"
 
 module IRB
   class Context
+    # Creates a new IRB context.
     #
-    # Arguments:
-    #   input_method: nil -- stdin or readline
-    #		      String -- File
-    #		      other -- using this as InputMethod
+    # The optional +input_method+ argument:
     #
+    # +nil+::     uses stdin or Readline
+    # +String+::  uses a File
+    # +other+::   uses this as InputMethod
     def initialize(irb, workspace = nil, input_method = nil, output_method = nil)
       @irb = irb
       if workspace
@@ -116,31 +117,69 @@ module IRB
     attr_accessor :irb_name
     attr_accessor :irb_path
 
+    # Whether +Readline+ is enabled or not.
+    #
+    # See #use_readline= for more information.
     attr_reader :use_readline
     attr_reader :inspect_mode
 
     attr_reader :prompt_mode
+    # Standard IRB prompt
+    #
+    # See IRB@Customizing+the+IRB+Prompt for more information.
     attr_accessor :prompt_i
+    # IRB prompt for continuated strings
+    #
+    # See IRB@Customizing+the+IRB+Prompt for more information.
     attr_accessor :prompt_s
+    # IRB prompt for continuated statement (e.g. immediately after an +if+)
+    #
+    # See IRB@Customizing+the+IRB+Prompt for more information.
     attr_accessor :prompt_c
+    # See IRB@Customizing+the+IRB+Prompt for more information.
     attr_accessor :prompt_n
     attr_accessor :auto_indent_mode
     attr_accessor :return_format
 
+    # Whether <code>^C</code> (+control-c+) will be ignored or not.
+    #
+    # If set to +false+, <code>^C</code> will quit irb.
+    #
+    # If set to +true+,
+    #
+    # * during input:   cancel input then return to top level.
+    # * during execute: abandon current execution.
     attr_accessor :ignore_sigint
+    # Whether <code>^D</code> (+control-d+) will be ignored or not.
+    #
+    # If set to +false+, <code>^D</code> will quit irb.
     attr_accessor :ignore_eof
     attr_accessor :echo
+    # Whether verbose messages are displayed or not.
     attr_accessor :verbose
+    # The debug level of irb
+    #
+    # See #debug_level= for more information.
     attr_reader :debug_level
 
+    # The limit of backtrace lines displayed as top +n+ and tail +n+.
+    #
+    # The default value is 16.
+    #
+    # Can also be set using the +--back-trace-limit+ command line option.
+    #
+    # See IRB@Command+line+options for more command line options.
     attr_accessor :back_trace_limit
 
+    # Alias for #use_readline
     alias use_readline? use_readline
+    # Alias for #rc
     alias rc? rc
     alias ignore_sigint? ignore_sigint
     alias ignore_eof? ignore_eof
     alias echo? echo
 
+    # Returns whether messages are displayed or not.
     def verbose?
       if @verbose.nil?
 	if defined?(ReadlineInputMethod) && @io.kind_of?(ReadlineInputMethod)
@@ -190,6 +229,17 @@ module IRB
       @io.class == FileInputMethod
     end
 
+    # Specifies the inspect mode with +opt+:
+    #
+    # +true+::  display +inspect+
+    # +false+:: display +to_s+
+    # +nil+::   inspect mode in non-math mode,
+    #           non-inspect mode in math mode
+    #
+    # Can also be set using the +--inspect+ and +--noinspect+ command line
+    # options.
+    #
+    # See IRB@Command+line+options for more command line options.
     def inspect_mode=(opt)
 
       if i = INSPECTORS[opt]
@@ -234,11 +284,27 @@ module IRB
     end
 
 
+    # Sets whether or not to use the Readline extension
+    #
+    # +true+::  enables +Readline+
+    # +false+:: disables +Readline+
+    # +nil+::   intends to use +Readline+,
+    #           except for when +inf-ruby-mode+ is active.
+    #
+    # Can also be set using the +--noreadline+ and +--readline+ command line
+    # options.
+    #
+    # See IRB@Command+line+options for more command line options.
     def use_readline=(opt)
       @use_readline = opt
       print "use readline module\n" if @use_readline
     end
 
+    # Sets the debug level of irb
+    #
+    # Can also be set using the +--irb_debug+ command line option.
+    #
+    # See IRB@Command+line+options for more command line options.
     def debug_level=(value)
       @debug_level = value
       RubyLex.debug_level = value
@@ -261,6 +327,7 @@ module IRB
     end
 
     alias __exit__ exit
+    # Exits the current session, see IRB.irb_exit
     def exit(ret = 0)
       IRB.irb_exit(@irb, ret)
     end
diff --git a/lib/irb/ext/change-ws.rb b/lib/irb/ext/change-ws.rb
index dea969d384..a28754e378 100644
--- a/lib/irb/ext/change-ws.rb
+++ b/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
diff --git a/lib/irb/ext/history.rb b/lib/irb/ext/history.rb
index 1495f9eb14..4d036e7cf0 100644
--- a/lib/irb/ext/history.rb
+++ b/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
diff --git a/lib/irb/ext/loader.rb b/lib/irb/ext/loader.rb
index 26a3203676..2058a2fa29 100644
--- a/lib/irb/ext/loader.rb
+++ b/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
diff --git a/lib/irb/ext/math-mode.rb b/lib/irb/ext/math-mode.rb
index 41be79841c..4f3c5c18ba 100644
--- a/lib/irb/ext/math-mode.rb
+++ b/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
diff --git a/lib/irb/ext/multi-irb.rb b/lib/irb/ext/multi-irb.rb
index a8475b75cd..473a4361b7 100644
--- a/lib/irb/ext/multi-irb.rb
+++ b/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
diff --git a/lib/irb/ext/use-loader.rb b/lib/irb/ext/use-loader.rb
index 64283b8989..913a64116f 100644
--- a/lib/irb/ext/use-loader.rb
+++ b/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
diff --git a/lib/irb/ext/workspaces.rb b/lib/irb/ext/workspaces.rb
index 118ea598c0..1232fee84f 100644
--- a/lib/irb/ext/workspaces.rb
+++ b/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"
diff --git a/lib/irb/extend-command.rb b/lib/irb/extend-command.rb
index 190c49ae78..3f37d39950 100644
--- a/lib/irb/extend-command.rb
+++ b/lib/irb/extend-command.rb
@@ -8,7 +8,7 @@
 #
 #
 #
-module IRB
+module IRB # :nodoc:
   #
   # IRB extended command
   #
@@ -23,6 +23,9 @@ module IRB
       irb_context.exit(ret)
     end
 
+    # Displays current configuration.
+    #
+    # Modifing the configuration is achieved by sending a message to IRB.conf.
     def irb_context
       IRB.CurrentContext
     end
diff --git a/lib/irb/init.rb b/lib/irb/init.rb
index fce2df4f09..35fa752c2b 100644
--- a/lib/irb/init.rb
+++ b/lib/irb/init.rb
@@ -9,7 +9,7 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
 
   # initialize config
   def IRB.setup(ap_path)
diff --git a/lib/irb/inspector.rb b/lib/irb/inspector.rb
index aefe077f37..6e93d3ccb9 100644
--- a/lib/irb/inspector.rb
+++ b/lib/irb/inspector.rb
@@ -10,7 +10,7 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
 
   def IRB::Inspector(inspect, init = nil)
     Inspector.new(inspect, init)
diff --git a/lib/irb/lc/error.rb b/lib/irb/lc/error.rb
index 742821e3af..57872ec65e 100644
--- a/lib/irb/lc/error.rb
+++ b/lib/irb/lc/error.rb
@@ -10,6 +10,7 @@
 #
 require "e2mmap"
 
+# :stopdoc:
 module IRB
 
   # exceptions
@@ -26,4 +27,4 @@ module IRB
   def_exception :UndefinedPromptMode, "Undefined prompt mode(%s)."
 
 end
-
+# :startdoc:
diff --git a/lib/irb/lc/ja/encoding_aliases.rb b/lib/irb/lc/ja/encoding_aliases.rb
index a713dff4be..5bef32e20e 100644
--- a/lib/irb/lc/ja/encoding_aliases.rb
+++ b/lib/irb/lc/ja/encoding_aliases.rb
@@ -1,3 +1,4 @@
+# :stopdoc:
 module IRB
   class Locale
     @@legacy_encoding_alias_map = {
@@ -6,3 +7,4 @@ module IRB
     }.freeze
   end
 end
+# :startdoc:
diff --git a/lib/irb/lc/ja/error.rb b/lib/irb/lc/ja/error.rb
index 9a7670f459..16a9138938 100644
--- a/lib/irb/lc/ja/error.rb
+++ b/lib/irb/lc/ja/error.rb
@@ -10,6 +10,7 @@
 #
 require "e2mmap"
 
+# :stopdoc:
 module IRB
   # exceptions
   extend Exception2MessageMapper
@@ -24,4 +25,5 @@ module IRB
   def_exception :CantChangeBinding, 'バインディング(%s)に変更できません.'
   def_exception :UndefinedPromptMode, 'プロンプトモード(%s)は定義されていません.'
 end
+# :startdoc:
 # vim:fileencoding=utf-8
diff --git a/lib/irb/locale.rb b/lib/irb/locale.rb
index 7781006da4..accce9e13f 100644
--- a/lib/irb/locale.rb
+++ b/lib/irb/locale.rb
@@ -8,7 +8,7 @@
 #
 #
 #
-module IRB
+module IRB # :nodoc:
   class Locale
     @RCS_ID='-$Id$-'
 
diff --git a/lib/irb/ruby-lex.rb b/lib/irb/ruby-lex.rb
index 2a23534bf3..068a672d40 100644
--- a/lib/irb/ruby-lex.rb
+++ b/lib/irb/ruby-lex.rb
@@ -13,6 +13,7 @@ require "e2mmap"
 require "irb/slex"
 require "irb/ruby-token"
 
+# :stopdoc:
 class RubyLex
   @RCS_ID='-$Id$-'
 
@@ -1185,3 +1186,4 @@ class RubyLex
     end
   end
 end
+# :startdoc:
diff --git a/lib/irb/ruby-token.rb b/lib/irb/ruby-token.rb
index 531fb859ff..2c7565dbfc 100644
--- a/lib/irb/ruby-token.rb
+++ b/lib/irb/ruby-token.rb
@@ -8,6 +8,7 @@
 #
 #
 #
+# :stopdoc:
 module RubyToken
   EXPR_BEG = :EXPR_BEG
   EXPR_MID = :EXPR_MID
@@ -263,3 +264,4 @@ module RubyToken
     def_token(*defs)
   end
 end
+# :startdoc:
diff --git a/lib/irb/slex.rb b/lib/irb/slex.rb
index b395eaa475..79be29cb4f 100644
--- a/lib/irb/slex.rb
+++ b/lib/irb/slex.rb
@@ -12,6 +12,7 @@
 require "e2mmap"
 require "irb/notifier"
 
+# :stopdoc:
 module IRB
   class SLex
     @RCS_ID='-$Id$-'
@@ -243,6 +244,7 @@ module IRB
     end
   end
 end
+# :startdoc:
 
 if $0 == __FILE__
   #    Tracer.on
diff --git a/lib/irb/version.rb b/lib/irb/version.rb
index 621a127ebd..bb998db3dd 100644
--- a/lib/irb/version.rb
+++ b/lib/irb/version.rb
@@ -9,7 +9,7 @@
 #
 #
 
-module IRB
+module IRB # :nodoc:
   @RELEASE_VERSION = "0.9.6"
   @LAST_UPDATE_DATE = "09/06/30"
 end
diff --git a/lib/irb/workspace.rb b/lib/irb/workspace.rb
index a8d4a90ad8..04490ba7c6 100644
--- a/lib/irb/workspace.rb
+++ b/lib/irb/workspace.rb
@@ -8,9 +8,11 @@
 #
 #
 #
-module IRB
+module IRB # :nodoc:
   class WorkSpace
-    # create new workspace. set self to main if specified, otherwise
+    # Creates a new workspace.
+    #
+    # set self to main if specified, otherwise
     # inherit main from TOPLEVEL_BINDING.
     def initialize(*main)
       if main[0].kind_of?(Binding)