* 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

28 files changed, 426 insertions, 23 deletions

diff --git a/lib/irb.rb b/lib/irb.rb
index c8fa04c4e5..e56b69bae0 100644
--- a/lib/irb.rb
+++ b/lib/irb.rb
@@ -21,14 +21,272 @@ require "irb/locale"
 
 STDOUT.sync = true
 
+# IRB stands for "interactive ruby" and is a tool to interactively execute ruby
+# expressions read from the standard input.
+#
+# The +irb+ command from your shell will start the interpreter.
+#
+# == Usage
+#
+# Use of irb is easy if you know ruby.
+#
+# When executing irb, prompts are displayed as follows. Then, enter the ruby
+# expression. An input is executed when it is syntactically complete.
+#
+#     $ irb
+#     irb(main):001:0> 1+2
+#     #=> 3
+#     irb(main):002:0> class Foo
+#     irb(main):003:1>  def foo
+#     irb(main):004:2>    print 1
+#     irb(main):005:2>  end
+#     irb(main):006:1> end
+#     #=> nil
+#
+# The Readline extension module can be used with irb. Use of Readline is
+# default if it's installed.
+#
+# == Command line options
+#
+#   Usage:  irb.rb [options] [programfile] [arguments]
+#     -f                Suppress read of ~/.irbrc
+#     -m                Bc mode (load mathn, fraction or matrix are available)
+#     -d                Set $DEBUG to true (same as `ruby -d')
+#     -r load-module    Same as `ruby -r'
+#     -I path           Specify $LOAD_PATH directory
+#     -U                Same as `ruby -U`
+#     -E enc            Same as `ruby -E`
+#     -w                Same as `ruby -w`
+#     -W[level=2]       Same as `ruby -W`
+#     --inspect         Use `inspect' for output (default except for bc mode)
+#     --noinspect       Don't use inspect for output
+#     --readline        Use Readline extension module
+#     --noreadline      Don't use Readline extension module
+#     --prompt prompt-mode
+#     --prompt-mode prompt-mode
+#                       Switch prompt mode. Pre-defined prompt modes are
+#                       `default', `simple', `xmp' and `inf-ruby'
+#     --inf-ruby-mode   Use prompt appropriate for inf-ruby-mode on emacs.
+#                       Suppresses --readline.
+#     --simple-prompt   Simple prompt mode
+#     --noprompt        No prompt mode
+#     --tracer          Display trace for each execution of commands.
+#     --back-trace-limit n
+#                       Display backtrace top n and tail n. The default
+#                       value is 16.
+#     --irb_debug n     Set internal debug level to n (not for popular use)
+#     -v, --version     Print the version of irb
+#
+# == Configuration
+#
+# IRB reads from <code>~/.irbrc</code> when it's invoked.
+#
+# If <code>~/.irbrc</code> doesn't exist, +irb+ will try to read in the following order:
+#
+# * +.irbrc+
+# * +irb.rc+
+# * +_irbrc+
+# * <code>$irbrc</code>
+#
+# The following are alternatives to the command line options. To use them type
+# as follows in an +irb+ session:
+#
+#     IRB.conf[:IRB_NAME]="irb"
+#     IRB.conf[:MATH_MODE]=false
+#     IRB.conf[:INSPECT_MODE]=nil
+#     IRB.conf[:IRB_RC] = nil
+#     IRB.conf[:BACK_TRACE_LIMIT]=16
+#     IRB.conf[:USE_LOADER] = false
+#     IRB.conf[:USE_READLINE] = nil
+#     IRB.conf[:USE_TRACER] = false
+#     IRB.conf[:IGNORE_SIGINT] = true
+#     IRB.conf[:IGNORE_EOF] = false
+#     IRB.conf[:PROMPT_MODE] = :DEFALUT
+#     IRB.conf[:PROMPT] = {...}
+#     IRB.conf[:DEBUG_LEVEL]=0
+#
+# == Customizing the IRB Prompt
+#
+# In order to customize the prompt, you can change the following Hash:
+#
+#     IRB.conf[:PROMPT]
+#
+# This example can be used in your +.irbrc+
+#
+#     IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode
+#       :PROMPT_I => nil,		# normal prompt
+#       :PROMPT_S => nil,		# prompt for continuated strings
+#       :PROMPT_C => nil,		# prompt for continuated statement
+#       :RETURN => "    ==>%s\n"	# format to return value
+#     }
+#
+# Then, invoke irb with the above prompt mode by:
+#
+#     irb --prompt my-prompt
+#
+# Or, add the following in your +.irbrc+:
+#
+#     IRB.conf[:PROMPT_MODE] = :MY_PROMPT
+#
+# Contants +PROMPT_I+, +PROMPT_S+ and +PROMPT_C+ specify the format. In the
+# prompt specification, some special strings are available:
+#
+#     %N    # command name which is running
+#     %m    # to_s of main object (self)
+#     %M    # inspect of main object (self)
+#     %l    # type of string(", ', /, ]), `]' is inner %w[...]
+#     %NNi  # indent level. NN is degits and means as same as printf("%NNd").
+#           # It can be ommited
+#     %NNn  # line number.
+#     %%    # %
+#
+# For instance, the default prompt mode is defined as follows:
+#
+#     IRB.conf[:PROMPT_MODE][:DEFAULT] = {
+#       :PROMPT_I => "%N(%m):%03n:%i> ",
+#       :PROMPT_S => "%N(%m):%03n:%i%l ",
+#       :PROMPT_C => "%N(%m):%03n:%i* ",
+#       :RETURN => "%s\n" # used to printf
+#     }
+#
+# == Restrictions
+#
+# Because irb evaluates input immediately after it is syntactically complete,
+# the results may be slightly different than directly using ruby.
+#
+# One of the obvious differences is how irb handles symbols as continuated
+# statements:
+#
+#   ruby -e 'p :+' #=> :+
+#   irb
+#   irb(main):001:0> p :+
+#   irb(main):002:0*
+#
+# irb tries to contiue the statement 'p :+' on the next line.
+#
+# == IRB Sessions
+#
+# IRB has a special feature, that allows you to manage many sessions at once.
+#
+# You can create new sessions with Irb.irb, and get a list of current sessions
+# with the +jobs+ command in the prompt.
+#
+# === Commands
+#
+# JobManager provides commands to handle the current sessions:
+#
+#   jobs    # List of current sessions
+#   fg      # Switches to the session of the given number
+#   kill    # Kills the session with the given number
+#
+# The +exit+ command, or ::irb_exit, will quit the current session and call any
+# exit hooks with IRB.irb_at_exit.
+#
+# A few commands for loading files within the session are also available:
+#
+# +source+::
+#   Loads a given file in the current session, see IrbLoader#source_file
+# +irb_load+::
+#   Loads the given file similarly to Kernel#load, see IrbLoader#irb_load
+# +irb_require+::
+#   Loads the given file similarly to Kernel#require
+#
+# === Configuration
+#
+# The command line options, or IRB.conf, specify the default behavior of
+# Irb.irb.
+#
+# On the other hand, each conf in IRB@Command+line+options is used to
+# individually configure IRB.irb.
+#
+# If a proc is set for IRB.conf[:IRB_RC], its will be invoked after execution
+# of that proc with the context of the current session as its argument. Each
+# session can be configured using this mechanism.
+#
+# === Session variables
+#
+# There are a few variables in every Irb session that can come in handy:
+#
+# <code>_</code>::
+#   The value command executed, as a local variable
+# <code>__</code>::
+#   The history of evaluated commands
+# <code>__[line_no]</code>::
+#   Returns the evaluation value at the given line number, +line_no+.
+#   If +line_no+ is a negative, the return value +line_no+ many lines before
+#   the most recent return value.
+#
+# === Example using IRB Sessions
+#
+#   # invoke a new session
+#   irb(main):001:0> irb
+#   # list open sessions
+#   irb.1(main):001:0> jobs
+#     #0->irb on main (#<Thread:0x400fb7e4> : stop)
+#     #1->irb#1 on main (#<Thread:0x40125d64> : running)
+#
+#   # change the active session
+#   irb.1(main):002:0> fg 0
+#   # define class Foo in top-level session
+#   irb(main):002:0> class Foo;end
+#   # invoke a new session with the context of Foo
+#   irb(main):003:0> irb Foo
+#   # define Foo#foo
+#   irb.2(Foo):001:0> def foo
+#   irb.2(Foo):002:1>   print 1
+#   irb.2(Foo):003:1> end
+#
+#   # change the active session
+#   irb.2(Foo):004:0> fg 0
+#   # list open sessions
+#   irb(main):004:0> jobs
+#     #0->irb on main (#<Thread:0x400fb7e4> : running)
+#     #1->irb#1 on main (#<Thread:0x40125d64> : stop)
+#     #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
+#   # check if Foo#foo is available
+#   irb(main):005:0> Foo.instance_methods #=> [:foo, ...]
+#
+#   # change the active sesssion
+#   irb(main):006:0> fg 2
+#   # define Foo#bar in the context of Foo
+#   irb.2(Foo):005:0> def bar
+#   irb.2(Foo):006:1>  print "bar"
+#   irb.2(Foo):007:1> end
+#   irb.2(Foo):010:0>  Foo.instance_methods #=> [:bar, :foo, ...]
+#
+#   # change the active session
+#   irb.2(Foo):011:0> fg 0
+#   irb(main):007:0> f = Foo.new  #=> #<Foo:0x4010af3c>
+#   # invoke a new session with the context of f (instance of Foo)
+#   irb(main):008:0> irb f
+#   # list open sessions
+#   irb.3(<Foo:0x4010af3c>):001:0> jobs
+#     #0->irb on main (#<Thread:0x400fb7e4> : stop)
+#     #1->irb#1 on main (#<Thread:0x40125d64> : stop)
+#     #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
+#     #3->irb#3 on #<Foo:0x4010af3c> (#<Thread:0x4010a1e0> : running)
+#   # evaluate f.foo
+#   irb.3(<Foo:0x4010af3c>):002:0> foo #=> 1 => nil
+#   # evaluate f.bar
+#   irb.3(<Foo:0x4010af3c>):003:0> bar #=> bar => nil
+#   # kill jobs 1, 2, and 3
+#   irb.3(<Foo:0x4010af3c>):004:0> kill 1, 2, 3
+#   # list open sesssions, should only include main session
+#   irb(main):009:0> jobs
+#     #0->irb on main (#<Thread:0x400fb7e4> : running)
+#   # quit irb
+#   irb(main):010:0> exit
 module IRB
   @RCS_ID='-$Id$-'
 
   class Abort < Exception;end
 
-  #
   @CONF = {}
 
+
+  # Displays current configuration.
+  #
+  # Modifing the configuration is achieved by sending a message to IRB.conf.
   def IRB.conf
     @CONF
   end
@@ -75,10 +333,12 @@ module IRB
 #    print "\n"
   end
 
+  # Calls each of the IRB.conf[:AT_EXIT] hooks when the current session quits.
   def IRB.irb_at_exit
     @CONF[:AT_EXIT].each{|hook| hook.call}
   end
 
+  # Quits irb
   def IRB.irb_exit(irb, ret)
     throw :IRB_EXIT, ret
   end
@@ -91,9 +351,7 @@ module IRB
     end
   end
 
-  #
   # irb interpreter main routine
-  #
   class Irb
     def initialize(workspace = nil, input_method = nil, output_method = nil)
       @context = Context.new(self, workspace, input_method, output_method)
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)