From ae294afa8d0a68d39613382d84cfba8821e48e38 Mon Sep 17 00:00:00 2001 From: Jamis Buck Date: Sun, 16 Oct 2005 03:00:44 +0000 Subject: [PATCH] Documentation updates/fixes for railties git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2637 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- railties/Rakefile | 10 +++++++++ railties/lib/binding_of_caller.rb | 4 +++- railties/lib/breakpoint.rb | 10 ++++----- railties/lib/breakpoint_client.rb | 2 +- railties/lib/code_statistics.rb | 2 +- railties/lib/commands/process/reaper.rb | 27 ++++++++++++++++++++---- railties/lib/commands/process/spinner.rb | 2 +- railties/lib/dispatcher.rb | 9 ++++++++ railties/lib/rubyprof_ext.rb | 2 +- railties/lib/webrick_server.rb | 17 ++++++++++----- 10 files changed, 66 insertions(+), 19 deletions(-) diff --git a/railties/Rakefile b/railties/Rakefile index 38b7ff27c2..d66c425e03 100644 --- a/railties/Rakefile +++ b/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 ---------------------------------------------------------------------------- diff --git a/railties/lib/binding_of_caller.rb b/railties/lib/binding_of_caller.rb index d18fbdef3d..c1f2cc7b4d 100644 --- a/railties/lib/binding_of_caller.rb +++ b/railties/lib/binding_of_caller.rb @@ -1,7 +1,9 @@ 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 diff --git a/railties/lib/breakpoint.rb b/railties/lib/breakpoint.rb index 42dd0bad81..327e43e8e3 100644 --- a/railties/lib/breakpoint.rb +++ b/railties/lib/breakpoint.rb @@ -462,7 +462,7 @@ module IRB # :nodoc: 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 @@ module IRB # :nodoc: end end - class WorkSpace + class WorkSpace #:nodoc: alias :old_evaluate :evaluate def evaluate(*args) @@ -491,7 +491,7 @@ module IRB # :nodoc: 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 @@ module IRB # :nodoc: 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 diff --git a/railties/lib/breakpoint_client.rb b/railties/lib/breakpoint_client.rb index d651b0f8a8..36b7469e88 100644 --- a/railties/lib/breakpoint_client.rb +++ b/railties/lib/breakpoint_client.rb @@ -81,7 +81,7 @@ end Options[:ServerURI] = ARGV[0] if ARGV[0] -module Handlers +module Handlers #:nodoc: extend self def breakpoint_handler(workspace, message) diff --git a/railties/lib/code_statistics.rb b/railties/lib/code_statistics.rb index 835adf233f..f1c0bf1f6a 100644 --- a/railties/lib/code_statistics.rb +++ b/railties/lib/code_statistics.rb @@ -1,4 +1,4 @@ -class CodeStatistics +class CodeStatistics #:nodoc: TEST_TYPES = ['Units', 'Functionals', 'Unit tests', 'Functional tests'] diff --git a/railties/lib/commands/process/reaper.rb b/railties/lib/commands/process/reaper.rb index 1a08cb1def..b99fd1efa2 100644 --- a/railties/lib/commands/process/reaper.rb +++ b/railties/lib/commands/process/reaper.rb @@ -4,8 +4,16 @@ require 'uri' 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 @@ class ProgramProcess 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 @@ class ProgramProcess 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 diff --git a/railties/lib/commands/process/spinner.rb b/railties/lib/commands/process/spinner.rb index 161623c622..af073c747f 100644 --- a/railties/lib/commands/process/spinner.rb +++ b/railties/lib/commands/process/spinner.rb @@ -1,6 +1,6 @@ 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]. diff --git a/railties/lib/dispatcher.rb b/railties/lib/dispatcher.rb index 958710ad66..a3382b3fc6 100644 --- a/railties/lib/dispatcher.rb +++ b/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 @@ class Dispatcher 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 diff --git a/railties/lib/rubyprof_ext.rb b/railties/lib/rubyprof_ext.rb index 0a1f4a5504..f6e90357ce 100644 --- a/railties/lib/rubyprof_ext.rb +++ b/railties/lib/rubyprof_ext.rb @@ -1,6 +1,6 @@ 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| diff --git a/railties/lib/webrick_server.rb b/railties/lib/webrick_server.rb index 734f87f6fd..f356eaf35e 100644 --- a/railties/lib/webrick_server.rb +++ b/railties/lib/webrick_server.rb @@ -10,7 +10,7 @@ ABSOLUTE_RAILS_ROOT = File.expand_path(RAILS_ROOT) ActiveRecord::Base.threaded_connections = false -class CGI +class CGI #:nodoc: def stdinput @stdin || $stdin end @@ -40,9 +40,16 @@ class CGI 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 /. def self.dispatch(options = {}) Socket.do_not_reverse_lookup = true # patch for OS X @@ -62,14 +69,14 @@ class DispatchServlet < WEBrick::HTTPServlet::AbstractServlet 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 @@ class DispatchServlet < WEBrick::HTTPServlet::AbstractServlet 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 @@ class DispatchServlet < WEBrick::HTTPServlet::AbstractServlet 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 || "")),