Documentation updates/fixes for railties

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2637 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

railties/Rakefile

@@ -227,6 +227,16 @@ task :generate_app_doc do
   system %{cd #{PKG_DESTINATION}; rake appdoc}
 end
 
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Railties -- Gluing the Engine to the Rails"
+  rdoc.options << '--line-numbers --inline-source --accessor cattr_accessor=object'
+  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
+  rdoc.rdoc_files.include('README', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/*.rb')
+  rdoc.rdoc_files.include('lib/rails_generator/*.rb')
+  rdoc.rdoc_files.include('lib/commands/**/*.rb')
+}
 
 # Generate GEM ----------------------------------------------------------------------------
 

railties/lib/binding_of_caller.rb

 begin
   require 'simplecc'
 rescue LoadError
-  class Continuation; end # :nodoc: # for RDoc
+  # to satisfy rdoc
+  class Continuation #:nodoc:
+  end
   def Continuation.create(*args, &block) # :nodoc:
     cc = nil; result = callcc {|c| cc = c; block.call(cc) if block and args.empty?}
     result ||= args

railties/lib/breakpoint.rb

@@ -462,7 +462,7 @@ def result.last_value; end
   end
   def IRB.parse_opts() end
 
-  class Context
+  class Context #:nodoc:
     alias :old_evaluate :evaluate
     def evaluate(line, line_no)
       if line.chomp == "exit" then
@@ -473,7 +473,7 @@ def evaluate(line, line_no)
     end
   end
 
-  class WorkSpace
+  class WorkSpace #:nodoc:
     alias :old_evaluate :evaluate
 
     def evaluate(*args)
@@ -491,7 +491,7 @@ def evaluate(*args)
     end
   end
 
-  module InputCompletor
+  module InputCompletor #:nodoc:
     def self.eval(code, context, *more)
       # Big hack, this assumes that InputCompletor
       # will only call eval() when it wants code
@@ -501,8 +501,8 @@ def self.eval(code, context, *more)
   end
 end
 
-module DRb # :nodoc:
-  class DRbObject
+module DRb #:nodoc:
+  class DRbObject #:nodoc:
     undef :inspect if method_defined?(:inspect)
     undef :clone if method_defined?(:clone)
   end

railties/lib/breakpoint_client.rb

@@ -81,7 +81,7 @@
 
 Options[:ServerURI] = ARGV[0] if ARGV[0]
 
-module Handlers
+module Handlers #:nodoc:
   extend self
 
   def breakpoint_handler(workspace, message)

railties/lib/code_statistics.rb

-class CodeStatistics
+class CodeStatistics #:nodoc:
 
   TEST_TYPES = ['Units', 'Functionals', 'Unit tests', 'Functional tests']
 

railties/lib/commands/process/reaper.rb

@@ -4,8 +4,16 @@
 
 if RUBY_PLATFORM =~ /mswin32/ then abort("Reaper is only for Unix") end
 
+# Instances of this class represent a single running process. Processes may
+# be queried by "keyword" to find those that meet a specific set of criteria.
 class ProgramProcess
   class << self
+    
+    # Searches for all processes matching the given keywords, and then invokes
+    # a specific action on each of them. This is useful for (e.g.) reloading a
+    # set of processes:
+    #
+    #   ProgramProcess.process_keywords(:reload, "basecamp")
     def process_keywords(action, *keywords)
       processes = keywords.collect { |keyword| find_by_keyword(keyword) }.flatten
 
@@ -19,6 +27,9 @@ def process_keywords(action, *keywords)
       end      
     end
 
+    # Searches for all processes matching the given keyword:
+    #
+    #   ProgramProcess.find_by_keyword("basecamp")
     def find_by_keyword(keyword)
       process_lines_with_keyword(keyword).split("\n").collect { |line|
         next if line.include?("inq") || line.include?("ps -ax") || line.include?("grep")
@@ -33,34 +44,42 @@ def process_lines_with_keyword(keyword)
       end
   end
 
+  # Create a new ProgramProcess instance that represents the process with the
+  # given pid, running the given command.
   def initialize(pid, command)
     @pid, @command = pid, command
   end
 
-  def find
-  end
-
+  # Forces the (rails) application to reload by sending a +HUP+ signal to the
+  # process.
   def reload
     `kill -s HUP #{@pid}`
   end
 
+  # Forces the (rails) application to gracefully terminate by sending a
+  # +TERM+ signal to the process.
   def graceful
     `kill -s TERM #{@pid}`
   end
 
+  # Forces the (rails) application to terminate immediately by sending a -9
+  # signal to the process.
   def kill
     `kill -9 #{@pid}`
   end
 
+  # Send a +USR1+ signal to the process.
   def usr1
     `kill -s USR1 #{@pid}`
   end
 
+  # Force the (rails) application to restart by sending a +USR2+ signal to the
+  # process.
   def restart
     `kill -s USR2 #{@pid}`
   end
 
-  def to_s
+  def to_s #:nodoc:
     "[#{@pid}] #{@command}"
   end
 end

railties/lib/commands/process/spinner.rb

 require 'optparse'
 
-def daemonize
+def daemonize #:nodoc:
   exit if fork                   # Parent exits, child continues.
   Process.setsid                 # Become session leader.
   exit if fork                   # Zap session leader. See [1].

railties/lib/dispatcher.rb

@@ -21,8 +21,14 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+# This class provides an interface for dispatching a CGI (or CGI-like) request
+# to the appropriate controller and action. It also takes care of resetting
+# the environment (when Dependencies.load? is true) after each request.
 class Dispatcher
   class << self
+    
+    # Dispatch the given CGI request, using the given session options, and
+    # emitting the output via the given output.
     def dispatch(cgi = CGI.new, session_options = ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS, output = $stdout)
       begin
         request, response = ActionController::CgiRequest.new(cgi, session_options), ActionController::CgiResponse.new(cgi)
@@ -35,6 +41,9 @@ def dispatch(cgi = CGI.new, session_options = ActionController::CgiRequest::DEFA
       end
     end
 
+    # Reset the application by clearing out loaded controllers, views, actions,
+    # mailers, and so forth. This allows them to be loaded again without having
+    # to restart the server (WEBrick, FastCGI, etc.).
     def reset_application!
       Controllers.clear!
       Dependencies.clear

railties/lib/rubyprof_ext.rb

 require 'prof'
 
-module Prof
+module Prof #:nodoc:
   # Adapted from Shugo Maeda's unprof.rb
   def self.print_profile(results, io = $stderr)
     total = results.detect { |i|

railties/lib/webrick_server.rb

@@ -10,7 +10,7 @@
 
 ActiveRecord::Base.threaded_connections = false
 
-class CGI
+class CGI #:nodoc:
   def stdinput
     @stdin || $stdin
   end
@@ -40,9 +40,16 @@ def initialize(type = "query", table = nil, stdin = nil)
   end
 end
 
+# A custom dispatch servlet for use with WEBrick. It dispatches requests
+# (using the Rails Dispatcher) to the appropriate controller/action. By default,
+# it restricts WEBrick to a managing a single Rails request at a time, but you
+# can change this behavior by setting ActionController::Base.allow_concurrency
+# to true.
 class DispatchServlet < WEBrick::HTTPServlet::AbstractServlet
   REQUEST_MUTEX = Mutex.new
 
+  # Start the WEBrick server with the given options, mounting the
+  # DispatchServlet at <tt>/</tt>.
   def self.dispatch(options = {})
     Socket.do_not_reverse_lookup = true # patch for OS X
 
@@ -62,14 +69,14 @@ def self.dispatch(options = {})
     server.start
   end
 
-  def initialize(server, options)
+  def initialize(server, options) #:nodoc:
     @server_options = options
     @file_handler = WEBrick::HTTPServlet::FileHandler.new(server, options[:server_root])
     Dir.chdir(ABSOLUTE_RAILS_ROOT)
     super
   end
 
-  def service(req, res)
+  def service(req, res) #:nodoc:
     begin
       unless handle_file(req, res)
         REQUEST_MUTEX.lock unless ActionController::Base.allow_concurrency
@@ -84,7 +91,7 @@ def service(req, res)
     end
   end
 
-  def handle_file(req, res)
+  def handle_file(req, res) #:nodoc:
     begin
       req = req.dup
       path = req.path.dup
@@ -105,7 +112,7 @@ def handle_file(req, res)
     end
   end
 
-  def handle_dispatch(req, res, origin = nil)    
+  def handle_dispatch(req, res, origin = nil) #:nodoc:
     data = StringIO.new
     Dispatcher.dispatch(
       CGI.new("query", create_env_table(req, origin), StringIO.new(req.body || "")),