eventmachine 1.0.0.beta.3 → 1.0.0.beta.4

data/lib/em/timers.rb

@@ -20,6 +20,7 @@ module EventMachine
 
   # Creates a periodic timer
   #
+  # @example
   #  n = 0
   #  timer = EventMachine::PeriodicTimer.new(5) do
   #    puts "the time is #{Time.now}"
@@ -44,10 +45,13 @@ module EventMachine
     # Fire the timer every interval seconds
     attr_accessor :interval
 
-    def schedule # :nodoc:
+    # @private
+    def schedule
       EventMachine::add_timer @interval, @work
     end
-    def fire # :nodoc:
+
+    # @private
+    def fire
       unless @cancelled
         @code.call
         schedule

data/lib/em/version.rb

@@ -1,3 +1,3 @@
 module EventMachine
-  VERSION = "1.0.0.beta.3"
+  VERSION = "1.0.0.beta.4"
 end

data/lib/eventmachine.rb

@@ -13,6 +13,7 @@ else
 end
 
 require 'em/version'
+require 'em/pool'
 require 'em/deferrable'
 require 'em/future'
 require 'em/streamer'
@@ -30,154 +31,132 @@ require 'em/file_watch'
 require 'em/process_watch'
 require 'em/tick_loop'
 require 'em/resolver'
+require 'em/completion'
+require 'em/threaded_resource'
 
 require 'shellwords'
 require 'thread'
 require 'resolv'
 
-# == Introduction
-# EventMachine provides a fast, lightweight framework for implementing
-# Ruby programs that can use the network to communicate with other
-# processes. Using EventMachine, Ruby programmers can easily connect
-# to remote servers and act as servers themselves. EventMachine does not
-# supplant the Ruby IP libraries. It does provide an alternate technique
-# for those applications requiring better performance, scalability,
-# and discipline over the behavior of network sockets, than is easily
-# obtainable using the built-in libraries, especially in applications
-# which are structurally well-suited for the event-driven programming model.
+# Top-level EventMachine namespace. If you are looking for EventMachine examples, see {file:docs/GettingStarted.md EventMachine tutorial}.
 #
-# EventMachine provides a perpetual event-loop which your programs can
-# start and stop. Within the event loop, TCP network connections are
-# initiated and accepted, based on EventMachine methods called by your
-# program. You also define callback methods which are called by EventMachine
-# when events of interest occur within the event-loop.
+# ## Key methods ##
+# ### Starting and stopping the event loop ###
 #
-# User programs will be called back when the following events occur:
-# * When the event loop accepts network connections from remote peers
-# * When data is received from network connections
-# * When connections are closed, either by the local or the remote side
-# * When user-defined timers expire
+# * {EventMachine.run}
+# * {EventMachine.stop_event_loop}
 #
-# == Usage example
+# ### Implementing clients ###
 #
-# Here's a fully-functional echo server implemented in EventMachine:
+# * {EventMachine.connect}
 #
-#  require 'eventmachine'
+# ### Implementing servers ###
 #
-#  module EchoServer
-#    def post_init
-#      puts "-- someone connected to the echo server!"
-#    end
+# * {EventMachine.start_server}
 #
-#    def receive_data data
-#      send_data ">>>you sent: #{data}"
-#      close_connection if data =~ /quit/i
-#    end
+# ### Working with timers ###
 #
-#    def unbind
-#      puts "-- someone disconnected from the echo server!"
-#    end
-#  end
+# * {EventMachine.add_timer}
+# * {EventMachine.add_periodic_timer}
+# * {EventMachine.cancel_timer}
 #
-#  EventMachine::run {
-#    EventMachine::start_server "127.0.0.1", 8081, EchoServer
-#  }
+# ### Working with blocking tasks ###
 #
-# What's going on here? Well, we have defined the module EchoServer to
-# implement the semantics of the echo protocol (more about that shortly).
-# The last three lines invoke the event-machine itself, which runs forever
-# unless one of your callbacks terminates it. The block that you supply
-# to EventMachine::run contains code that runs immediately after the event
-# machine is initialized and before it starts looping. This is the place
-# to open up a TCP server by specifying the address and port it will listen
-# on, together with the module that will process the data.
-# 
-# Our EchoServer is extremely simple as the echo protocol doesn't require
-# much work. Basically you want to send back to the remote peer whatever
-# data it sends you. We'll dress it up with a little extra text to make it
-# interesting. Also, we'll close the connection in case the received data
-# contains the word "quit."
-# 
-# So what about this module EchoServer? Well, whenever a network connection
-# (either a client or a server) starts up, EventMachine instantiates an anonymous
-# class, that your module has been mixed into. Exactly one of these class
-# instances is created for each connection. Whenever an event occurs on a
-# given connection, its corresponding object automatically calls specific
-# instance methods which your module may redefine. The code in your module
-# always runs in the context of a class instance, so you can create instance
-# variables as you wish and they will be carried over to other callbacks
-# made on that same connection.
-# 
-# Looking back up at EchoServer, you can see that we've defined the method
-# receive_data which (big surprise) is called whenever data has been received
-# from the remote end of the connection. Very simple. We get the data
-# (a String object) and can do whatever we wish with it. In this case,
-# we use the method send_data to return the received data to the caller,
-# with some extra text added in. And if the user sends the word "quit,"
-# we'll close the connection with (naturally) close_connection.
-# (Notice that closing the connection doesn't terminate the processing loop,
-# or change the fact that your echo server is still accepting connections!) 
+# * {EventMachine.defer}
+# * {EventMachine.next_tick}
 #
-# == Questions and Futures
-# Would it be useful for EventMachine to incorporate the Observer pattern
-# and make use of the corresponding Ruby <tt>observer</tt> package?
-# Interesting thought.
+# ### Efficient proxying ###
 #
+# * {EventMachine.enable_proxy}
+# * {EventMachine.disable_proxy}
 module EventMachine
   class << self
     # Exposed to allow joining on the thread, when run in a multithreaded
     # environment. Performing other actions on the thread has undefined
-    # semantics.
+    # semantics (read: a dangerous endevor).
+    #
+    # @return [Thread]
     attr_reader :reactor_thread
   end
   @next_tick_mutex = Mutex.new
   @reactor_running = false
   @next_tick_queue = []
+  @tails = []
   @threadpool = nil
-  
-
-  # EventMachine::run initializes and runs an event loop.
-  # This method only returns if user-callback code calls stop_event_loop.
-  # Use the supplied block to define your clients and servers.
-  # The block is called by EventMachine::run immediately after initializing
-  # its internal event loop but <i>before</i> running the loop.
-  # Therefore this block is the right place to call start_server if you
-  # want to accept connections from remote clients.
-  #
-  # For programs that are structured as servers, it's usually appropriate
-  # to start an event loop by calling EventMachine::run, and let it
-  # run forever. It's also possible to use EventMachine::run to make a single
-  # client-connection to a remote server, process the data flow from that
-  # single connection, and then call stop_event_loop to force EventMachine::run
-  # to return. Your program will then continue from the point immediately
-  # following the call to EventMachine::run.
-  #
-  # You can of course do both client and servers simultaneously in the same program.
-  # One of the strengths of the event-driven programming model is that the
-  # handling of network events on many different connections will be interleaved,
-  # and scheduled according to the actual events themselves. This maximizes
-  # efficiency.
-  #
-  # === Server usage example
-  #
-  # See EventMachine.start_server
-  #
-  # === Client usage example
-  #
-  # See EventMachine.connect
-  #
-  #--
-  # Obsoleted the use_threads mechanism.
-  # 25Nov06: Added the begin/ensure block. We need to be sure that release_machine
-  # gets called even if an exception gets thrown within any of the user code
-  # that the event loop runs. The best way to see this is to run a unit
-  # test with two functions, each of which calls EventMachine#run and each of
-  # which throws something inside of #run. Without the ensure, the second test
-  # will start without release_machine being called and will immediately throw
-  # a C++ runtime error.
+
+  # System errnos
+  # @private
+  ERRNOS = Errno::constants.grep(/^E/).inject(Hash.new(:unknown)) { |hash, name|
+    errno = Errno.__send__(:const_get, name)
+    hash[errno::Errno] = errno
+    hash
+  }
+
+  # Initializes and runs an event loop. This method only returns if code inside the block passed to this method
+  # calls {EventMachine.stop_event_loop}. The block is executed after initializing its internal event loop but *before* running the loop,
+  # therefore this block is the right place to call any code that needs event loop to run, for example, {EventMachine.start_server},
+  # {EventMachine.connect} or similar methods of libraries that use EventMachine under the hood
+  # (like `EventMachine::HttpRequest.new` or `AMQP.start`).
+  #
+  # Programs that are run for long periods of time (e.g. servers) usually start event loop by calling {EventMachine.run}, and let it
+  # run "forever". It's also possible to use {EventMachine.run} to make a single client-connection to a remote server,
+  # process the data flow from that single connection, and then call {EventMachine.stop_event_loop} to stop, in other words,
+  # to run event loop for a short period of time (necessary to complete some operation) and then shut it down.
+  #
+  # Once event loop is running, it is perfectly possible to start multiple servers and clients simultaneously: content-aware
+  # proxies like [Proxymachine](https://github.com/mojombo/proxymachine) do just that.
+  #
+  # ## Using EventMachine with Ruby on Rails and other Web application frameworks ##
+  #
+  # Standalone applications often run event loop on the main thread, thus blocking for their entire lifespan. In case of Web applications,
+  # if you are running an EventMachine-based app server such as [Thin](http://code.macournoyer.com/thin/) or [Goliath](https://github.com/postrank-labs/goliath/),
+  # they start event loop for you. Servers like Unicorn, Apache Passenger or Mongrel occupy main Ruby thread to serve HTTP(S) requests. This means
+  # that calling {EventMachine.run} on the same thread is not an option (it will result in Web server never binding to the socket).
+  # In that case, start event loop in a separate thread as demonstrated below.
+  #
+  #
+  # @example Starting EventMachine event loop in the current thread to run the "Hello, world"-like Echo server example
+  #
+  #   #!/usr/bin/env ruby
+  #
+  #   require 'rubygems' # or use Bundler.setup
+  #   require 'eventmachine'
+  #
+  #   class EchoServer < EM::Connection
+  #     def receive_data(data)
+  #       send_data(data)
+  #     end
+  #   end
+  #
+  #   EventMachine.run do
+  #     EventMachine.start_server("0.0.0.0", 10000, EchoServer)
+  #   end
+  #
   #
+  # @example Starting EventMachine event loop in a separate thread
+  #
+  #   # doesn't block current thread, can be used with Ruby on Rails, Sinatra, Merb, Rack
+  #   # and any other application server that occupies main Ruby thread.
+  #   Thread.new { EventMachine.run }
+  #
+  #
+  # @note This method blocks calling thread. If you need to start EventMachine event loop from a Web app
+  #       running on a non event-driven server (Unicorn, Apache Passenger, Mongrel), do it in a separate thread like demonstrated
+  #       in one of the examples.
+  # @see file:docs/GettingStarted.md Getting started with EventMachine
+  # @see EventMachine.stop_event_loop
   def self.run blk=nil, tail=nil, &block
-    @tails ||= []
+    # Obsoleted the use_threads mechanism.
+    # 25Nov06: Added the begin/ensure block. We need to be sure that release_machine
+    # gets called even if an exception gets thrown within any of the user code
+    # that the event loop runs. The best way to see this is to run a unit
+    # test with two functions, each of which calls {EventMachine.run} and each of
+    # which throws something inside of #run. Without the ensure, the second test
+    # will start without release_machine being called and will immediately throw
+
+    #
+
+
     tail and @tails.unshift(tail)
 
     if reactor_running?
@@ -188,6 +167,7 @@ module EventMachine
       @timers = {}
       @wrapped_exception = nil
       @next_tick_queue ||= []
+      @tails ||= []
       begin
         @reactor_running = true
         initialize_event_machine
@@ -235,8 +215,8 @@ module EventMachine
 
   # Sugars a common use case. Will pass the given block to #run, but will terminate
   # the reactor loop and exit the function as soon as the code in the block completes.
-  # (Normally, #run keeps running indefinitely, even after the block supplied to it
-  # finishes running, until user code calls #stop.)
+  # (Normally, {EventMachine.run} keeps running indefinitely, even after the block supplied to it
+  # finishes running, until user code calls {EventMachine.stop})
   #
   def self.run_block &block
     pr = proc {
@@ -246,13 +226,13 @@ module EventMachine
     run(&pr)
   end
 
-  # Returns true if the calling thread is the same thread as the reactor.
+  # @return [Boolean] true if the calling thread is the same thread as the reactor.
   def self.reactor_thread?
     Thread.current == @reactor_thread
   end
 
   # Runs the given callback on the reactor thread, or immediately if called
-  # from the reactor thread. Accepts the same arguments as EM::Callback
+  # from the reactor thread. Accepts the same arguments as {EventMachine::Callback}
   def self.schedule(*a, &b)
     cb = Callback(*a, &b)
     if reactor_running? && reactor_thread?
@@ -262,13 +242,12 @@ module EventMachine
     end
   end
 
-  # fork_reactor forks a new process and calls EM#run inside of it, passing your block.
-  #--
-  # This implementation is subject to change, especially if we clean up the relationship
-  # of EM#run to @reactor_running.
-  # Original patch by Aman Gupta.
-  #
+  # Forks a new process, properly stops the reactor and then calls {EventMachine.run} inside of it again, passing your block.
   def self.fork_reactor &block
+    # This implementation is subject to change, especially if we clean up the relationship
+    # of EM#run to @reactor_running.
+    # Original patch by Aman Gupta.
+    #
     Kernel.fork do
       if self.reactor_running?
         self.stop_event_loop
@@ -279,43 +258,54 @@ module EventMachine
     end
   end
 
-  # EventMachine#add_timer adds a one-shot timer to the event loop.
+  # Adds a block to call as the reactor is shutting down.
+  #
+  # These callbacks are called in the _reverse_ order to which they are added.
+  #
+  # @example Scheduling operations to be run when EventMachine event loop is stopped
+  #
+  #   EventMachine.run do
+  #     EventMachine.add_shutdown_hook { puts "b" }
+  #     EventMachine.add_shutdown_hook { puts "a" }
+  #     EventMachine.stop
+  #   end
+  #
+  #   # Outputs:
+  #   #   a
+  #   #   b
+  #
+  def self.add_shutdown_hook &block
+    @tails << block
+  end
+
+  # Adds a one-shot timer to the event loop.
   # Call it with one or two parameters. The first parameters is a delay-time
-  # expressed in <i>seconds</i> (not milliseconds). The second parameter, if
-  # present, must be a proc object. If a proc object is not given, then you
+  # expressed in *seconds* (not milliseconds). The second parameter, if
+  # present, must be an object that responds to :call. If 2nd parameter is not given, then you
   # can also simply pass a block to the method call.
   #
-  # EventMachine#add_timer may be called from the block passed to EventMachine#run
+  # This method may be called from the block passed to {EventMachine.run}
   # or from any callback method. It schedules execution of the proc or block
-  # passed to add_timer, after the passage of an interval of time equal to
-  # <i>at least</i> the number of seconds specified in the first parameter to
+  # passed to it, after the passage of an interval of time equal to
+  # *at least* the number of seconds specified in the first parameter to
   # the call.
   #
-  # EventMachine#add_timer is a <i>non-blocking</i> call. Callbacks can and will
+  # {EventMachine.add_timer} is a non-blocking method. Callbacks can and will
   # be called during the interval of time that the timer is in effect.
   # There is no built-in limit to the number of timers that can be outstanding at
   # any given time.
   #
-  # === Usage example
-  #
-  # This example shows how easy timers are to use. Observe that two timers are
-  # initiated simultaneously. Also, notice that the event loop will continue
-  # to run even after the second timer event is processed, since there was
-  # no call to EventMachine#stop_event_loop. There will be no activity, of
-  # course, since no network clients or servers are defined. Stop the program
-  # with Ctrl-C.
+  # @example Setting a one-shot timer with EventMachine
   #
-  #  EventMachine::run {
+  #  EventMachine.run {
   #    puts "Starting the run now: #{Time.now}"
-  #    EventMachine::add_timer 5, proc { puts "Executing timer event: #{Time.now}" }
-  #    EventMachine::add_timer( 10 ) { puts "Executing timer event: #{Time.now}" }
+  #    EventMachine.add_timer 5, proc { puts "Executing timer event: #{Time.now}" }
+  #    EventMachine.add_timer(10) { puts "Executing timer event: #{Time.now}" }
   #  }
   #
-  #
-  # Also see EventMachine::Timer
-  #--
-  # Changed 04Oct06: We now pass the interval as an integer number of milliseconds.
-  #
+  # @param [Integer] delay Delay in seconds
+  # @see EventMachine::Timer
+  # @see EventMachine.add_periodic_timer
   def self.add_timer *args, &block
     interval = args.shift
     code = args.shift || block
@@ -327,24 +317,22 @@ module EventMachine
     end
   end
 
-  # EventMachine#add_periodic_timer adds a periodic timer to the event loop.
-  # It takes the same parameters as the one-shot timer method, EventMachine#add_timer.
+  # Adds a periodic timer to the event loop.
+  # It takes the same parameters as the one-shot timer method, {EventMachine.add_timer}.
   # This method schedules execution of the given block repeatedly, at intervals
-  # of time <i>at least</i> as great as the number of seconds given in the first
+  # of time *at least* as great as the number of seconds given in the first
   # parameter to the call.
-  # 
-  # === Usage example
   #
-  # The following sample program will write a dollar-sign to stderr every five seconds.
-  # (Of course if the program defined network clients and/or servers, they would
-  # be doing their work while the periodic timer is counting off.)
+  # @example Write a dollar-sign to stderr every five seconds, without blocking
   #
-  #  EventMachine::run {
-  #    EventMachine::add_periodic_timer( 5 ) { $stderr.write "$" }
+  #  EventMachine.run {
+  #    EventMachine.add_periodic_timer( 5 ) { $stderr.write "$" }
   #  }
   #
+  # @param [Integer] delay Delay in seconds
   #
-  # Also see EventMachine::PeriodicTimer
+  # @see EventMachine::PeriodicTimer
+  # @see EventMachine.add_timer
   #
   def self.add_periodic_timer *args, &block
     interval = args.shift
@@ -353,8 +341,11 @@ module EventMachine
     EventMachine::PeriodicTimer.new(interval, code)
   end
 
-  # Cancel a timer using its signature. You can also use EventMachine::Timer#cancel
+
+  # Cancel a timer (can be a callback or an {EventMachine::Timer} instance).
   #
+  # @param [#cancel, #call] timer_or_sig A timer to cancel
+  # @see EventMachine::Timer#cancel
   def self.cancel_timer timer_or_sig
     if timer_or_sig.respond_to? :cancel
       timer_or_sig.cancel
@@ -364,19 +355,14 @@ module EventMachine
   end
 
 
-  # stop_event_loop may called from within a callback method
-  # while EventMachine's processing loop is running.
-  # It causes the processing loop to stop executing, which
-  # will cause all open connections and accepting servers
-  # to be run down and closed. <i>Callbacks for connection-termination
-  # will be called</i> as part of the processing of stop_event_loop.
-  # (There currently is no option to panic-stop the loop without
-  # closing connections.) When all of this processing is complete,
-  # the call to EventMachine::run which started the processing loop
-  # will return and program flow will resume from the statement
-  # following EventMachine::run call.
+  # Causes the processing loop to stop executing, which will cause all open connections and accepting servers
+  # to be run down and closed. Connection termination callbacks added using {EventMachine.add_shutdown_hook}
+  # will be called as part of running this method.
+  #
+  # When all of this processing is complete, the call to {EventMachine.run} which started the processing loop
+  # will return and program flow will resume from the statement following {EventMachine.run} call.
   #
-  # === Usage example
+  # @example Stopping a running EventMachine event loop
   #
   #  require 'rubygems'
   #  require 'eventmachine'
@@ -386,40 +372,40 @@ module EventMachine
   #      puts "We're sending a dumb HTTP request to the remote peer."
   #      send_data "GET / HTTP/1.1\r\nHost: www.microsoft.com\r\n\r\n"
   #    end
-  #  
+  #
   #    def receive_data data
   #      puts "We received #{data.length} bytes from the remote peer."
   #      puts "We're going to stop the event loop now."
   #      EventMachine::stop_event_loop
   #    end
-  #  
+  #
   #    def unbind
   #      puts "A connection has terminated."
   #    end
   #  end
-  #  
+  #
   #  puts "We're starting the event loop now."
-  #  EventMachine::run {
-  #    EventMachine::connect "www.microsoft.com", 80, Redmond
+  #  EventMachine.run {
+  #    EventMachine.connect "www.microsoft.com", 80, Redmond
   #  }
   #  puts "The event loop has stopped."
-  #  
-  # This program will produce approximately the following output:
   #
-  #  We're starting the event loop now.
-  #  We're sending a dumb HTTP request to the remote peer.
-  #  We received 1440 bytes from the remote peer.
-  #  We're going to stop the event loop now.
-  #  A connection has terminated.
-  #  The event loop has stopped.
+  #  # This program will produce approximately the following output:
+  #  #
+  #  # We're starting the event loop now.
+  #  # We're sending a dumb HTTP request to the remote peer.
+  #  # We received 1440 bytes from the remote peer.
+  #  # We're going to stop the event loop now.
+  #  # A connection has terminated.
+  #  # The event loop has stopped.
   #
   #
   def self.stop_event_loop
     EventMachine::stop
   end
 
-  # EventMachine::start_server initiates a TCP server (socket
-  # acceptor) on the specified IP address and port.
+  # Initiates a TCP server (socket acceptor) on the specified IP address and port.
+  #
   # The IP address must be valid on the machine where the program
   # runs, and the process must be privileged enough to listen
   # on the specified port (on Unix-like systems, superuser privileges
@@ -427,35 +413,37 @@ module EventMachine
   # Only one listener may be running on any given address/port
   # combination. start_server will fail if the given address and port
   # are already listening on the machine, either because of a prior call
-  # to start_server or some unrelated process running on the machine.
-  # If start_server succeeds, the new network listener becomes active
+  # to {.start_server} or some unrelated process running on the machine.
+  # If {.start_server} succeeds, the new network listener becomes active
   # immediately and starts accepting connections from remote peers,
   # and these connections generate callback events that are processed
-  # by the code specified in the handler parameter to start_server.
+  # by the code specified in the handler parameter to {.start_server}.
   #
-  # The optional handler which is passed to start_server is the key
+  # The optional handler which is passed to this method is the key
   # to EventMachine's ability to handle particular network protocols.
   # The handler parameter passed to start_server must be a Ruby Module
   # that you must define. When the network server that is started by
   # start_server accepts a new connection, it instantiates a new
-  # object of an anonymous class that is inherited from EventMachine::Connection,
-  # <i>into which the methods from your handler have been mixed.</i>
-  # Your handler module may redefine any of the methods in EventMachine::Connection
-  # in order to implement the specific behavior of the network protocol.
+  # object of an anonymous class that is inherited from {EventMachine::Connection},
+  # *into which your handler module have been included*.
   #
-  # Callbacks invoked in response to network events <i>always</i> take place
-  # within the execution context of the object derived from EventMachine::Connection
+  # Your handler module may override any of the methods in {EventMachine::Connection},
+  # such as {EventMachine::Connection#receive_data}, in order to implement the specific behavior
+  # of the network protocol.
+  #
+  # Callbacks invoked in response to network events *always* take place
+  # within the execution context of the object derived from {EventMachine::Connection}
   # extended by your handler module. There is one object per connection, and
   # all of the callbacks invoked for a particular connection take the form
-  # of instance methods called against the corresponding EventMachine::Connection
+  # of instance methods called against the corresponding {EventMachine::Connection}
   # object. Therefore, you are free to define whatever instance variables you
   # wish, in order to contain the per-connection state required by the network protocol you are
   # implementing.
   #
-  # start_server is often called inside the block passed to EventMachine::run,
-  # but it can be called from any EventMachine callback. start_server will fail
+  # {EventMachine.start_server} is usually called inside the block passed to {EventMachine.run},
+  # but it can be called from any EventMachine callback. {EventMachine.start_server} will fail
   # unless the EventMachine event loop is currently running (which is why
-  # it's often called in the block suppled to EventMachine::run).
+  # it's often called in the block suppled to {EventMachine.run}).
   #
   # You may call start_server any number of times to start up network
   # listeners on different address/port combinations. The servers will
@@ -463,29 +451,29 @@ module EventMachine
   # can specify a different handler module and thus implement a different
   # network protocol from all the others.
   #
-  # === Usage example
-  # Here is an example of a server that counts lines of input from the remote
-  # peer and sends back the total number of lines received, after each line.
-  # Try the example with more than one client connection opened via telnet,
-  # and you will see that the line count increments independently on each
-  # of the client connections. Also very important to note, is that the
-  # handler for the receive_data function, which our handler redefines, may
-  # not assume that the data it receives observes any kind of message boundaries.
-  # Also, to use this example, be sure to change the server and port parameters
-  # to the start_server call to values appropriate for your environment.
+  # @example
   #
   #  require 'rubygems'
   #  require 'eventmachine'
   #
+  #  # Here is an example of a server that counts lines of input from the remote
+  #  # peer and sends back the total number of lines received, after each line.
+  #  # Try the example with more than one client connection opened via telnet,
+  #  # and you will see that the line count increments independently on each
+  #  # of the client connections. Also very important to note, is that the
+  #  # handler for the receive_data function, which our handler redefines, may
+  #  # not assume that the data it receives observes any kind of message boundaries.
+  #  # Also, to use this example, be sure to change the server and port parameters
+  #  # to the start_server call to values appropriate for your environment.
   #  module LineCounter
   #    MaxLinesPerConnection = 10
-  #  
+  #
   #    def post_init
   #      puts "Received a new connection"
   #      @data_received = ""
   #      @line_count = 0
   #    end
-  #  
+  #
   #    def receive_data data
   #      @data_received << data
   #      while @data_received.slice!( /^[^\n]*[\n]/m )
@@ -495,15 +483,22 @@ module EventMachine
   #      end
   #    end
   #  end
-  #  
-  #  EventMachine::run {
-  #    host,port = "192.168.0.100", 8090
-  #    EventMachine::start_server host, port, LineCounter
+  #
+  #  EventMachine.run {
+  #    host, port = "192.168.0.100", 8090
+  #    EventMachine.start_server host, port, LineCounter
   #    puts "Now accepting connections on address #{host}, port #{port}..."
-  #    EventMachine::add_periodic_timer( 10 ) { $stderr.write "*" }
+  #    EventMachine.add_periodic_timer(10) { $stderr.write "*" }
   #  }
-  #  
   #
+  # @param [String] server         Host to bind to.
+  # @param [Integer] port          Port to bind to.
+  # @param [Module, Class] handler A module or class that implements connection callbacks
+  #
+  # @note Don't forget that in order to bind to ports < 1024 on Linux, *BSD and Mac OS X your process must have superuser privileges.
+  #
+  # @see file:docs/GettingStarted.md EventMachine tutorial
+  # @see EventMachine.stop_server
   def self.start_server server, port=nil, handler=nil, *args, &block
     begin
       port = Integer(port)
@@ -527,122 +522,118 @@ module EventMachine
   end
 
 
-  # Stop a TCP server socket that was started with EventMachine#start_server.
-  #--
-  # Requested by Kirk Haines. TODO, this isn't OOP enough. We ought somehow
-  # to have #start_server return an object that has a close or a stop method on it.
-  #
+  # Stop a TCP server socket that was started with {EventMachine.start_server}.
+  # @see EventMachine.start_server
   def self.stop_server signature
     EventMachine::stop_tcp_server signature
   end
 
-  # Start a Unix-domain server
+  # Start a Unix-domain server.
+  #
+  # Note that this is an alias for {EventMachine.start_server}, which can be used to start both
+  # TCP and Unix-domain servers.
   #
-  # Note that this is an alias for EventMachine::start_server, which can be used to start both
-  # TCP and Unix-domain servers
+  # @see EventMachine.start_server
   def self.start_unix_domain_server filename, *args, &block
     start_server filename, *args, &block
   end
 
-  # EventMachine#connect initiates a TCP connection to a remote
-  # server and sets up event-handling for the connection.
-  # You can call EventMachine#connect in the block supplied
-  # to EventMachine#run or in any callback method.
+  # Initiates a TCP connection to a remote server and sets up event handling for the connection.
+  # {EventMachine.connect} requires event loop to be running (see {EventMachine.run}).
   #
-  # EventMachine#connect takes the IP address (or hostname) and
+  # {EventMachine.connect} takes the IP address (or hostname) and
   # port of the remote server you want to connect to.
-  # It also takes an optional handler Module which you must define, that
-  # contains the callbacks that will be invoked by the event loop
-  # on behalf of the connection.
+  # It also takes an optional handler (a module or a subclass of {EventMachine::Connection}) which you must define, that
+  # contains the callbacks that will be invoked by the event loop on behalf of the connection.
   #
-  # See the description of EventMachine#start_server for a discussion
-  # of the handler Module. All of the details given in that description
-  # apply for connections created with EventMachine#connect.
+  # Learn more about connection lifecycle callbacks in the {file:docs/GettingStarted.md EventMachine tutorial} and
+  # {file:docs/ConnectionLifecycleCallbacks.md Connection lifecycle guide}.
   #
-  # === Usage Example
   #
-  # Here's a program which connects to a web server, sends a naive
-  # request, parses the HTTP header of the response, and then
-  # (antisocially) ends the event loop, which automatically drops the connection
-  # (and incidentally calls the connection's unbind method).
-  # 
+  # @example
+  #
+  #  # Here's a program which connects to a web server, sends a naive
+  #  # request, parses the HTTP header of the response, and then
+  #  # (antisocially) ends the event loop, which automatically drops the connection
+  #  # (and incidentally calls the connection's unbind method).
   #  module DumbHttpClient
   #    def post_init
   #      send_data "GET / HTTP/1.1\r\nHost: _\r\n\r\n"
   #      @data = ""
   #      @parsed = false
   #    end
-  #  
+  #
   #    def receive_data data
   #      @data << data
   #      if !@parsed and @data =~ /[\n][\r]*[\n]/m
   #        @parsed = true
   #        puts "RECEIVED HTTP HEADER:"
   #        $`.each {|line| puts ">>> #{line}" }
-  #  
+  #
   #        puts "Now we'll terminate the loop, which will also close the connection"
   #        EventMachine::stop_event_loop
   #      end
   #    end
-  #  
+  #
   #    def unbind
   #      puts "A connection has terminated"
   #    end
   #  end
-  #  
-  #  EventMachine::run {
-  #    EventMachine::connect "www.bayshorenetworks.com", 80, DumbHttpClient
+  #
+  #  EventMachine.run {
+  #    EventMachine.connect "www.bayshorenetworks.com", 80, DumbHttpClient
   #  }
   #  puts "The event loop has ended"
-  #  
   #
-  # There are times when it's more convenient to define a protocol handler
-  # as a Class rather than a Module. Here's how to do this:
+  #
+  # @example Defining protocol handler as a class
   #
   #  class MyProtocolHandler < EventMachine::Connection
   #    def initialize *args
   #      super
   #      # whatever else you want to do here
   #    end
-  #    
-  #    #.......your other class code
+  #
+  #    # ...
   #  end
   #
-  # If you do this, then an instance of your class will be instantiated to handle
-  # every network connection created by your code or accepted by servers that you
-  # create. If you redefine #post_init in your protocol-handler class, your
-  # #post_init method will be called _inside_ the call to #super that you will
-  # make in your #initialize method (if you provide one).
-  #
-  #--
-  # EventMachine::connect initiates a TCP connection to a remote
-  # server and sets up event-handling for the connection.
-  # It internally creates an object that should not be handled
-  # by the caller. HOWEVER, it's often convenient to get the
-  # object to set up interfacing to other objects in the system.
-  # We return the newly-created anonymous-class object to the caller.
-  # It's expected that a considerable amount of code will depend
-  # on this behavior, so don't change it.
-  #
-  # Ok, added support for a user-defined block, 13Apr06.
-  # This leads us to an interesting choice because of the
-  # presence of the post_init call, which happens in the
-  # initialize method of the new object. We call the user's
-  # block and pass the new object to it. This is a great
-  # way to do protocol-specific initiation. It happens
-  # AFTER post_init has been called on the object, which I
-  # certainly hope is the right choice.
-  # Don't change this lightly, because accepted connections
-  # are different from connected ones and we don't want
-  # to have them behave differently with respect to post_init
-  # if at all possible.
   #
+  # @param [String] server         Host to connect to
+  # @param [Integer] port          Port to connect to
+  # @param [Module, Class] handler A module or class that implements connection lifecycle callbacks
+  #
+  # @see EventMachine.start_server
+  # @see file:docs/GettingStarted.md EventMachine tutorial
   def self.connect server, port=nil, handler=nil, *args, &blk
+    # EventMachine::connect initiates a TCP connection to a remote
+    # server and sets up event-handling for the connection.
+    # It internally creates an object that should not be handled
+    # by the caller. HOWEVER, it's often convenient to get the
+    # object to set up interfacing to other objects in the system.
+    # We return the newly-created anonymous-class object to the caller.
+    # It's expected that a considerable amount of code will depend
+    # on this behavior, so don't change it.
+    #
+    # Ok, added support for a user-defined block, 13Apr06.
+    # This leads us to an interesting choice because of the
+    # presence of the post_init call, which happens in the
+    # initialize method of the new object. We call the user's
+    # block and pass the new object to it. This is a great
+    # way to do protocol-specific initiation. It happens
+    # AFTER post_init has been called on the object, which I
+    # certainly hope is the right choice.
+    # Don't change this lightly, because accepted connections
+    # are different from connected ones and we don't want
+    # to have them behave differently with respect to post_init
+    # if at all possible.
+
     bind_connect nil, nil, server, port, handler, *args, &blk
   end
 
-  # EventMachine::bind_connect is like EventMachine::connect, but allows for a local address/port
+  # This method is like {EventMachine.connect}, but allows for a local address/port
   # to bind the connection to.
+  #
+  # @see EventMachine.connect
   def self.bind_connect bind_addr, bind_port, server, port=nil, handler=nil, *args
     begin
       port = Integer(port)
@@ -672,18 +663,18 @@ module EventMachine
     c
   end
 
-  # EventMachine::watch registers a given file descriptor or IO object with the eventloop. The
+  # {EventMachine.watch} registers a given file descriptor or IO object with the eventloop. The
   # file descriptor will not be modified (it will remain blocking or non-blocking).
   #
   # The eventloop can be used to process readable and writable events on the file descriptor, using
-  # EventMachine::Connection#notify_readable= and EventMachine::Connection#notify_writable=
+  # {EventMachine::Connection#notify_readable=} and {EventMachine::Connection#notify_writable=}
   #
-  # EventMachine::Connection#notify_readable? and EventMachine::Connection#notify_writable? can be used
+  # {EventMachine::Connection#notify_readable?} and {EventMachine::Connection#notify_writable?} can be used
   # to check what events are enabled on the connection.
   #
-  # To detach the file descriptor, use EventMachine::Connection#detach
+  # To detach the file descriptor, use {EventMachine::Connection#detach}
   #
-  # === Usage Example
+  # @example
   #
   #  module SimpleHttpClient
   #    def notify_readable
@@ -705,15 +696,14 @@ module EventMachine
   #    end
   #  end
   #
-  #  EM.run{
-  #    $sock = TCPSocket.new('site.com', 80)
-  #    $sock.write("GET / HTTP/1.0\r\n\r\n")
-  #    conn = EM.watch $sock, SimpleHttpClient
+  #  EventMachine.run {
+  #    sock = TCPSocket.new('site.com', 80)
+  #    sock.write("GET / HTTP/1.0\r\n\r\n")
+  #    conn = EventMachine.watch(sock, SimpleHttpClient)
   #    conn.notify_readable = true
   #  }
   #
-  #--
-  # Thanks to Riham Aldakkak (eSpace Technologies) for the initial patch
+  # @author Riham Aldakkak (eSpace Technologies)
   def EventMachine::watch io, handler=nil, *args, &blk
     attach_io io, true, handler, *args, &blk
   end
@@ -722,13 +712,14 @@ module EventMachine
   # The file descriptor will be set as non-blocking, and EventMachine will process
   # receive_data and send_data events on it as it would for any other connection.
   #
-  # To watch a fd instead, use EventMachine::watch, which will not alter the state of the socket
+  # To watch a fd instead, use {EventMachine.watch}, which will not alter the state of the socket
   # and fire notify_readable and notify_writable events instead.
   def EventMachine::attach io, handler=nil, *args, &blk
     attach_io io, false, handler, *args, &blk
   end
 
-  def EventMachine::attach_io io, watch_mode, handler=nil, *args # :nodoc:
+  # @private
+  def EventMachine::attach_io io, watch_mode, handler=nil, *args
     klass = klass_from_handler(Connection, handler, *args)
 
     if !watch_mode and klass.public_instance_methods.any?{|m| [:notify_readable, :notify_writable].include? m.to_sym }
@@ -753,17 +744,19 @@ module EventMachine
   end
 
 
-  # Connect to a given host/port and re-use the provided EventMachine::Connection instance
-  #--
-  # Observe, the test for already-connected FAILS if we call a reconnect inside post_init,
-  # because we haven't set up the connection in @conns by that point.
-  # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init.
-  #
-  # Changed 22Nov06: if called on an already-connected handler, just return the
-  # handler and do nothing more. Originally this condition raised an exception.
-  # We may want to change it yet again and call the block, if any.
+  # Connect to a given host/port and re-use the provided {EventMachine::Connection} instance.
+  # Consider also {EventMachine::Connection#reconnect}.
   #
-  def self.reconnect server, port, handler # :nodoc:
+  # @see EventMachine::Connection#reconnect
+  def self.reconnect server, port, handler
+    # Observe, the test for already-connected FAILS if we call a reconnect inside post_init,
+    # because we haven't set up the connection in @conns by that point.
+    # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init.
+    #
+    # Changed 22Nov06: if called on an already-connected handler, just return the
+    # handler and do nothing more. Originally this condition raised an exception.
+    # We may want to change it yet again and call the block, if any.
+
     raise "invalid handler" unless handler.respond_to?(:connection_completed)
     #raise "still connected" if @conns.has_key?(handler.signature)
     return handler if @conns.has_key?(handler.signature)
@@ -776,90 +769,77 @@ module EventMachine
   end
 
 
-  # Make a connection to a Unix-domain socket. This is not implemented on Windows platforms.
-  # The parameter socketname is a String which identifies the Unix-domain socket you want
-  # to connect to. socketname is the name of a file on your local system, and in most cases
-  # is a fully-qualified path name. Make sure that your process has enough local permissions
-  # to open the Unix-domain socket.
-  # See also the documentation for #connect. This method behaves like #connect
-  # in all respects except for the fact that it connects to a local Unix-domain
-  # socket rather than a TCP socket.
-  #
-  # Note that this method is simply an alias for #connect, which can connect to both TCP
-  # and Unix-domain sockets
-  #--
-  # For making connections to Unix-domain sockets.
-  # Eventually this has to get properly documented and unified with the TCP-connect methods.
-  # Note how nearly identical this is to EventMachine#connect
+  # Make a connection to a Unix-domain socket. This method is simply an alias for {.connect},
+  # which can connect to both TCP and Unix-domain sockets. Make sure that your process has sufficient
+  # permissions to open the socket it is given.
+  #
+  # @param [String] socketname Unix domain socket (local fully-qualified path) you want to connect to.
+  #
+  # @note UNIX sockets, as the name suggests, are not available on Microsoft Windows.
   def self.connect_unix_domain socketname, *args, &blk
     connect socketname, *args, &blk
   end
 
 
-  # EventMachine#open_datagram_socket is for support of UDP-based
-  # protocols. Its usage is similar to that of EventMachine#start_server.
-  # It takes three parameters: an IP address (which must be valid
-  # on the machine which executes the method), a port number,
-  # and an optional Module name which will handle the data.
+  # Used for UDP-based protocols. Its usage is similar to that of {EventMachine.start_server}.
+  #
   # This method will create a new UDP (datagram) socket and
   # bind it to the address and port that you specify.
-  # The normal callbacks (see EventMachine#start_server) will
+  # The normal callbacks (see {EventMachine.start_server}) will
   # be called as events of interest occur on the newly-created
   # socket, but there are some differences in how they behave.
   #
-  # Connection#receive_data will be called when a datagram packet
+  # {Connection#receive_data} will be called when a datagram packet
   # is received on the socket, but unlike TCP sockets, the message
   # boundaries of the received data will be respected. In other words,
   # if the remote peer sent you a datagram of a particular size,
-  # you may rely on Connection#receive_data to give you the
+  # you may rely on {Connection#receive_data} to give you the
   # exact data in the packet, with the original data length.
   # Also observe that Connection#receive_data may be called with a
-  # <i>zero-length</i> data payload, since empty datagrams are permitted
-  # in UDP.
+  # *zero-length* data payload, since empty datagrams are permitted in UDP.
   #
-  # Connection#send_data is available with UDP packets as with TCP,
+  # {Connection#send_data} is available with UDP packets as with TCP,
   # but there is an important difference. Because UDP communications
-  # are <i>connectionless,</i> there is no implicit recipient for the packets you
+  # are *connectionless*, there is no implicit recipient for the packets you
   # send. Ordinarily you must specify the recipient for each packet you send.
-  # However, EventMachine
-  # provides for the typical pattern of receiving a UDP datagram
+  # However, EventMachine provides for the typical pattern of receiving a UDP datagram
   # from a remote peer, performing some operation, and then sending
   # one or more packets in response to the same remote peer.
-  # To support this model easily, just use Connection#send_data
-  # in the code that you supply for Connection:receive_data.
-  # EventMachine will
-  # provide an implicit return address for any messages sent to
-  # Connection#send_data within the context of a Connection#receive_data callback,
+  # To support this model easily, just use {Connection#send_data}
+  # in the code that you supply for {Connection#receive_data}.
+  #
+  # EventMachine will provide an implicit return address for any messages sent to
+  # {Connection#send_data} within the context of a {Connection#receive_data} callback,
   # and your response will automatically go to the correct remote peer.
-  # (TODO: Example-code needed!)
   #
-  # Observe that the port number that you supply to EventMachine#open_datagram_socket
+  # Observe that the port number that you supply to {EventMachine.open_datagram_socket}
   # may be zero. In this case, EventMachine will create a UDP socket
-  # that is bound to an <i>ephemeral</i> (not well-known) port.
+  # that is bound to an [ephemeral port](http://en.wikipedia.org/wiki/Ephemeral_port).
   # This is not appropriate for servers that must publish a well-known
   # port to which remote peers may send datagrams. But it can be useful
   # for clients that send datagrams to other servers.
   # If you do this, you will receive any responses from the remote
-  # servers through the normal Connection#receive_data callback.
+  # servers through the normal {Connection#receive_data} callback.
   # Observe that you will probably have issues with firewalls blocking
   # the ephemeral port numbers, so this technique is most appropriate for LANs.
-  # (TODO: Need an example!)
   #
   # If you wish to send datagrams to arbitrary remote peers (not
   # necessarily ones that have sent data to which you are responding),
-  # then see Connection#send_datagram.
+  # then see {Connection#send_datagram}.
   #
-  # DO NOT call send_data from a datagram socket
-  # outside of a #receive_data method. Use #send_datagram. If you do use #send_data
-  # outside of a #receive_data method, you'll get a confusing error
-  # because there is no "peer," as #send_data requires. (Inside of #receive_data,
-  # #send_data "fakes" the peer as described above.)
-  #
-  #--
-  # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
-  # out that this originally did not take a class but only a module.
+  # DO NOT call send_data from a datagram socket outside of a {Connection#receive_data} method. Use {Connection#send_datagram}.
+  # If you do use {Connection#send_data} outside of a {Connection#receive_data} method, you'll get a confusing error
+  # because there is no "peer," as #send_data requires (inside of {EventMachine::Connection#receive_data},
+  # {EventMachine::Connection#send_data} "fakes" the peer as described above).
   #
+  # @param [String]         address IP address
+  # @param [String]         port    Port
+  # @param [Class, Module]  handler A class or a module that implements connection lifecycle callbacks.
   def self.open_datagram_socket address, port, handler=nil, *args
+    # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing
+    # out that this originally did not take a class but only a module.
+
+
     klass = klass_from_handler(Connection, handler, *args)
     s = open_udp_socket address, port.to_i
     c = klass.new s, *args
@@ -871,31 +851,42 @@ module EventMachine
 
   # For advanced users. This function sets the default timer granularity, which by default is
   # slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity.
-  # The function affects the behavior of #add_timer and #add_periodic_timer. Most applications
-  # will not need to call this function.
+  # The function affects the behavior of {EventMachine.add_timer} and {EventMachine.add_periodic_timer}.
+  # Most applications will not need to call this function.
+  #
+  # Avoid setting the quantum to very low values because that may reduce performance under some extreme conditions.
+  # We recommend that you not use values lower than 10.
   #
-  # The argument is a number of milliseconds. Avoid setting the quantum to very low values because
-  # that may reduce performance under some extreme conditions. We recommend that you not set a quantum
-  # lower than 10.
+  # This method only can be used if event loop is running.
   #
-  # You may only call this function while an EventMachine loop is running (that is, after a call to
-  # EventMachine#run and before a subsequent call to EventMachine#stop).
+  # @param [Integer] mills New timer granularity, in milliseconds
   #
+  # @see EventMachine.add_timer
+  # @see EventMachine.add_periodic_timer
+  # @see EventMachine::Timer
+  # @see EventMachine.run
   def self.set_quantum mills
     set_timer_quantum mills.to_i
   end
 
   # Sets the maximum number of timers and periodic timers that may be outstanding at any
-  # given time. You only need to call #set_max_timers if you need more than the default
+  # given time. You only need to call {.set_max_timers} if you need more than the default
   # number of timers, which on most platforms is 1000.
-  # Call this method before calling EventMachine#run.
   #
+  # @note This method has to be used *before* event loop is started.
+  #
+  # @param [Integer] ct Maximum number of timers that may be outstanding at any given time
+  #
+  # @see EventMachine.add_timer
+  # @see EventMachine.add_periodic_timer
+  # @see EventMachine::Timer
   def self.set_max_timers ct
     set_max_timer_count ct
   end
 
   # Gets the current maximum number of allowed timers
   #
+  # @return [Integer] Maximum number of timers that may be outstanding at any given time
   def self.get_max_timers
     get_max_timer_count
   end
@@ -904,35 +895,42 @@ module EventMachine
   # Note that a tick must pass after the 'initiation' of a connection for this number to increment.
   # It's usually accurate, but don't rely on the exact precision of this number unless you really know EM internals.
   #
-  # For example, $count will be 0 in this case:
+  # @example
   #
-  #  EM.run {
-  #    EM.connect("rubyeventmachine.com", 80)
-  #    $count = EM.connection_count
+  #  EventMachine.run {
+  #    EventMachine.connect("rubyeventmachine.com", 80)
+  #    # count will be 0 in this case, because connection is not
+  #    # established yet
+  #    count = EventMachine.connection_count
   #  }
   #
-  # In this example, $count will be 1 since the connection has been established in the next loop of the reactor.
   #
-  #  EM.run {
-  #    EM.connect("rubyeventmachine.com", 80)
-  #    EM.next_tick {
-  #      $count = EM.connection_count
+  # @example
+  #
+  #  EventMachine.run {
+  #    EventMachine.connect("rubyeventmachine.com", 80)
+  #
+  #    EventMachine.next_tick {
+  #      # In this example, count will be 1 since the connection has been established in
+  #      # the next loop of the reactor.
+  #      count = EventMachine.connection_count
   #    }
   #  }
   #
+  # @return [Integer] Number of connections currently held by the reactor.
   def self.connection_count
     self.get_connection_count
   end
 
-  #--
   # The is the responder for the loopback-signalled event.
-  # It can be fired either by code running on a separate thread (EM#defer) or on
-  # the main thread (EM#next_tick).
+  # It can be fired either by code running on a separate thread ({EventMachine.defer}) or on
+  # the main thread ({EventMachine.next_tick}).
   # It will often happen that a next_tick handler will reschedule itself. We
   # consume a copy of the tick queue so that tick events scheduled by tick events
   # have to wait for the next pass through the reactor core.
   #
-  def self.run_deferred_callbacks # :nodoc:
+  # @private
+  def self.run_deferred_callbacks
     until (@resultqueue ||= []).empty?
       result,cback = @resultqueue.pop
       cback.call result if cback
@@ -945,50 +943,53 @@ module EventMachine
   end
 
 
-  # #defer is for integrating blocking operations into EventMachine's control flow.
-  # Call #defer with one or two blocks, as shown below (the second block is <i>optional</i>):
-  #
-  #  operation = proc {
-  #    # perform a long-running operation here, such as a database query.
-  #    "result" # as usual, the last expression evaluated in the block will be the return value.
-  #  }
-  #  callback = proc {|result|
-  #    # do something with result here, such as send it back to a network client.
-  #  }
-  #
-  #  EventMachine.defer( operation, callback )
-  #
-  # The action of #defer is to take the block specified in the first parameter (the "operation")
+  # EventMachine.defer is used for integrating blocking operations into EventMachine's control flow.
+  # The action of {.defer} is to take the block specified in the first parameter (the "operation")
   # and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine.
   # When the operation completes, it will pass the result computed by the block (if any)
   # back to the EventMachine reactor. Then, EventMachine calls the block specified in the
-  # second parameter to #defer (the "callback"), as part of its normal, synchronous
-  # event handling loop. The result computed by the operation block is passed as a parameter
-  # to the callback. You may omit the callback parameter if you don't need to execute any code
-  # after the operation completes.
+  # second parameter to {.defer} (the "callback"), as part of its normal event handling loop.
+  # The result computed by the operation block is passed as a parameter to the callback.
+  # You may omit the callback parameter if you don't need to execute any code after the operation completes.
+  #
+  # ## Caveats ##
   #
-  # == Caveats
   # Note carefully that the code in your deferred operation will be executed on a separate
   # thread from the main EventMachine processing and all other Ruby threads that may exist in
   # your program. Also, multiple deferred operations may be running at once! Therefore, you
-  # are responsible for ensuring that your operation code is threadsafe. [Need more explanation
-  # and examples.]
+  # are responsible for ensuring that your operation code is threadsafe.
+  #
   # Don't write a deferred operation that will block forever. If so, the current implementation will
   # not detect the problem, and the thread will never be returned to the pool. EventMachine limits
   # the number of threads in its pool, so if you do this enough times, your subsequent deferred
-  # operations won't get a chance to run. [We might put in a timer to detect this problem.]
+  # operations won't get a chance to run.
+  #
+  # @example
+  #
+  #  operation = proc {
+  #    # perform a long-running operation here, such as a database query.
+  #    "result" # as usual, the last expression evaluated in the block will be the return value.
+  #  }
+  #  callback = proc {|result|
+  #    # do something with result here, such as send it back to a network client.
+  #  }
   #
-  #--
-  # OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here
-  # without syncing there.
+  #  EventMachine.defer(operation, callback)
   #
-  # Running with $VERBOSE set to true gives a warning unless all ivars are defined when
-  # they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we
-  # need it, because the Ruby threads are so heavyweight. We end up with this bizarre
-  # way of initializing @threadqueue because EventMachine is a Module, not a Class, and
-  # has no constructor.
+  # @param [#call] op       An operation you want to offload to EventMachine thread pool
+  # @param [#call] callback A callback that will be run on the event loop thread after `operation` finishes.
   #
+  # @see EventMachine.threadpool_size
   def self.defer op = nil, callback = nil, &blk
+    # OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here
+    # without syncing there.
+    #
+    # Running with $VERBOSE set to true gives a warning unless all ivars are defined when
+    # they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we
+    # need it, because the Ruby threads are so heavyweight. We end up with this bizarre
+    # way of initializing @threadqueue because EventMachine is a Module, not a Class, and
+    # has no constructor.
+
     unless @threadpool
       require 'thread'
       @threadpool = []
@@ -1000,7 +1001,9 @@ module EventMachine
     @threadqueue << [op||blk,callback]
   end
 
-  def self.spawn_threadpool # :nodoc:
+
+  # @private
+  def self.spawn_threadpool
     until @threadpool.size == @threadpool_size.to_i
       thread = Thread.new do
         Thread.current.abort_on_exception = true
@@ -1016,9 +1019,11 @@ module EventMachine
   end
 
   class << self
-    attr_reader :threadpool # :nodoc:
+    # @private
+    attr_reader :threadpool
 
     # Size of the EventMachine.defer threadpool (defaults to 20)
+    # @return [Number]
     attr_accessor :threadpool_size
     EventMachine.threadpool_size = 20
   end
@@ -1026,19 +1031,20 @@ module EventMachine
   # Schedules a proc for execution immediately after the next "turn" through the reactor
   # core. An advanced technique, this can be useful for improving memory management and/or
   # application responsiveness, especially when scheduling large amounts of data for
-  # writing to a network connection. TODO, we need a FAQ entry on this subject.
-  #
-  # #next_tick takes either a single argument (which must be a Proc) or a block.
-  #--
-  # This works by adding to the @resultqueue that's used for #defer.
-  # The general idea is that next_tick is used when we want to give the reactor a chance
-  # to let other operations run, either to balance the load out more evenly, or to let
-  # outbound network buffers drain, or both. So we probably do NOT want to block, and
-  # we probably do NOT want to be spinning any threads. A program that uses next_tick
-  # but not #defer shouldn't suffer the penalty of having Ruby threads running. They're
-  # extremely expensive even if they're just sleeping.
+  # writing to a network connection.
   #
+  # This method takes either a single argument (which must be a callable object) or a block.
+  #
+  # @param [#call] pr A callable object to run
   def self.next_tick pr=nil, &block
+    # This works by adding to the @resultqueue that's used for #defer.
+    # The general idea is that next_tick is used when we want to give the reactor a chance
+    # to let other operations run, either to balance the load out more evenly, or to let
+    # outbound network buffers drain, or both. So we probably do NOT want to block, and
+    # we probably do NOT want to be spinning any threads. A program that uses next_tick
+    # but not #defer shouldn't suffer the penalty of having Ruby threads running. They're
+    # extremely expensive even if they're just sleeping.
+
     raise ArgumentError, "no proc or block given" unless ((pr && pr.respond_to?(:call)) or block)
     @next_tick_mutex.synchronize do
       @next_tick_queue << ( pr || block )
@@ -1048,42 +1054,44 @@ module EventMachine
 
   # A wrapper over the setuid system call. Particularly useful when opening a network
   # server on a privileged port because you can use this call to drop privileges
-  # after opening the port. Also very useful after a call to #set_descriptor_table_size,
+  # after opening the port. Also very useful after a call to {.set_descriptor_table_size},
   # which generally requires that you start your process with root privileges.
   #
-  # This method has no effective implementation on Windows or in the pure-Ruby
-  # implementation of EventMachine.
-  # Call #set_effective_user by passing it a string containing the effective name
-  # of the user whose privilege-level your process should attain.
   # This method is intended for use in enforcing security requirements, consequently
   # it will throw a fatal error and end your program if it fails.
   #
+  # @param [String] username The effective name of the user whose privilege-level your process should attain.
+  #
+  # @note This method has no effective implementation on Windows or in the pure-Ruby
+  #       implementation of EventMachine
   def self.set_effective_user username
     EventMachine::setuid_string username
   end
 
 
   # Sets the maximum number of file or socket descriptors that your process may open.
-  # You can pass this method an integer specifying the new size of the descriptor table.
-  # Returns the new descriptor-table size, which may be less than the number you
-  # requested. If you call this method with no arguments, it will simply return
+  # If you call this method with no arguments, it will simply return
   # the current size of the descriptor table without attempting to change it.
   #
-  # The new limit on open descriptors ONLY applies to sockets and other descriptors
-  # that belong to EventMachine. It has NO EFFECT on the number of descriptors
+  # The new limit on open descriptors **only** applies to sockets and other descriptors
+  # that belong to EventMachine. It has **no effect** on the number of descriptors
   # you can create in ordinary Ruby code.
   #
   # Not available on all platforms. Increasing the number of descriptors beyond its
-  # default limit usually requires superuser privileges. (See #set_effective_user
+  # default limit usually requires superuser privileges. (See {.set_effective_user}
   # for a way to drop superuser privileges while your program is running.)
   #
+  # @param [Integer] n_descriptors The maximum number of file or socket descriptors that your process may open
+  # @return [Integer] The new descriptor table size.
   def self.set_descriptor_table_size n_descriptors=nil
     EventMachine::set_rlimit_nofile n_descriptors
   end
 
 
 
-  # Run an external process. This does not currently work on Windows.
+  # Runs an external process.
+  #
+  # @example
   #
   #  module RubyCounter
   #    def post_init
@@ -1098,16 +1106,17 @@ module EventMachine
   #    end
   #  end
   #
-  #  EM.run{
-  #    EM.popen("ruby -e' $stdout.sync = true; gets.to_i.times{ |i| puts i+1; sleep 1 } '", RubyCounter)
+  #  EventMachine.run {
+  #    EventMachine.popen("ruby -e' $stdout.sync = true; gets.to_i.times{ |i| puts i+1; sleep 1 } '", RubyCounter)
   #  }
   #
-  # Also see EventMachine::DeferrableChildProcess and EventMachine.system
-  #--
-  # At this moment, it's only available on Unix.
-  # Perhaps misnamed since the underlying function uses socketpair and is full-duplex.
-  #
+  # @note This method is not supported on Microsoft Windows
+  # @see EventMachine::DeferrableChildProcess
+  # @see EventMachine.system
   def self.popen cmd, handler=nil, *args
+    # At this moment, it's only available on Unix.
+    # Perhaps misnamed since the underlying function uses socketpair and is full-duplex.
+
     klass = klass_from_handler(Connection, handler, *args)
     w = Shellwords::shellwords( cmd )
     w.unshift( w.first ) if w.first
@@ -1119,16 +1128,15 @@ module EventMachine
   end
 
 
-  # Tells you whether the EventMachine reactor loop is currently running. Returns true or
-  # false. Useful when writing libraries that want to run event-driven code, but may
-  # be running in programs that are already event-driven. In such cases, if EventMachine#reactor_running?
-  # returns false, your code can invoke EventMachine#run and run your application code inside
-  # the block passed to that method. If EventMachine#reactor_running? returns true, just
-  # execute your event-aware code.
+  # Tells you whether the EventMachine reactor loop is currently running.
   #
-  # This method is necessary because calling EventMachine#run inside of another call to
-  # EventMachine#run generates a fatal error.
+  # Useful when writing libraries that want to run event-driven code, but may
+  # be running in programs that are already event-driven. In such cases, if {EventMachine.reactor_running?}
+  # returns false, your code can invoke {EventMachine.run} and run your application code inside
+  # the block passed to that method. If this method returns true, just
+  # execute your event-aware code.
   #
+  # @return [Boolean] true if the EventMachine reactor loop is currently running
   def self.reactor_running?
     (@reactor_running || false)
   end
@@ -1136,7 +1144,7 @@ module EventMachine
 
   # (Experimental)
   #
-  #
+  # @private
   def self.open_keyboard handler=nil, *args
     klass = klass_from_handler(Connection, handler, *args)
 
@@ -1148,7 +1156,7 @@ module EventMachine
   end
 
   # EventMachine's file monitoring API. Currently supported are the following events
-  # on individual files, using inotify on Linux systems, and kqueue for OSX/BSD:
+  # on individual files, using inotify on Linux systems, and kqueue for *BSD and Mac OS X:
   #
   # * File modified (written to)
   # * File moved/renamed
@@ -1156,26 +1164,26 @@ module EventMachine
   #
   # EventMachine::watch_file takes a filename and a handler Module containing your custom callback methods.
   # This will setup the low level monitoring on the specified file, and create a new EventMachine::FileWatch
-  # object with your Module mixed in. FileWatch is a subclass of EM::Connection, so callbacks on this object
+  # object with your Module mixed in. FileWatch is a subclass of {EventMachine::Connection}, so callbacks on this object
   # work in the familiar way. The callbacks that will be fired by EventMachine are:
   #
   # * file_modified
   # * file_moved
   # * file_deleted
   #
-  # You can access the filename being monitored from within this object using FileWatch#path.
+  # You can access the filename being monitored from within this object using {FileWatch#path}.
   #
-  # When a file is deleted, FileWatch#stop_watching will be called after your file_deleted callback, 
-  # to clean up the underlying monitoring and remove EventMachine's reference to the now-useless FileWatch.
+  # When a file is deleted, {FileWatch#stop_watching} will be called after your file_deleted callback,
+  # to clean up the underlying monitoring and remove EventMachine's reference to the now-useless {FileWatch} instance.
   # This will in turn call unbind, if you wish to use it.
   #
   # The corresponding system-level Errno will be raised when attempting to monitor non-existent files,
   # files with wrong permissions, or if an error occurs dealing with inotify/kqueue.
   #
-  # === Usage example:
+  # @example
   #
-  #  Make sure we have a file to monitor:
-  #  $ echo "bar" > /tmp/foo
+  #  # Before running this example, make sure we have a file to monitor:
+  #  # $ echo "bar" > /tmp/foo
   #
   #  module Handler
   #    def file_modified
@@ -1195,20 +1203,22 @@ module EventMachine
   #    end
   #  end
   #
-  #  EM.kqueue = true if EM.kqueue? # file watching requires kqueue on OSX
+  #  # for efficient file watching, use kqueue on Mac OS X
+  #  EventMachine.kqueue = true if EventMachine.kqueue?
   #
-  #  EM.run {
-  #    EM.watch_file("/tmp/foo", Handler)
+  #  EventMachine.run {
+  #    EventMachine.watch_file("/tmp/foo", Handler)
   #  }
   #
-  #  $ echo "baz" >> /tmp/foo    =>    "/tmp/foo modified"
-  #  $ mv /tmp/foo /tmp/oof      =>    "/tmp/foo moved"
-  #  $ rm /tmp/oof               =>    "/tmp/foo deleted"
-  #                              =>    "/tmp/foo monitoring ceased"
+  #  # $ echo "baz" >> /tmp/foo    =>    "/tmp/foo modified"
+  #  # $ mv /tmp/foo /tmp/oof      =>    "/tmp/foo moved"
+  #  # $ rm /tmp/oof               =>    "/tmp/foo deleted"
   #
-  # Note that we have not implemented the ability to pick up on the new filename after a rename.
-  # Calling #path will always return the filename you originally used.
+  # @note The ability to pick up on the new filename after a rename is not yet supported.
+  #       Calling #path will always return the filename you originally used.
   #
+  # @param [String]        filename Local path to the file to watch.
+  # @param [Class, Module] handler  A class or module that implements event handlers associated with the file.
   def self.watch_file(filename, handler=nil, *args)
     klass = klass_from_handler(FileWatch, handler, *args)
 
@@ -1221,9 +1231,9 @@ module EventMachine
     c
   end
 
-  # EventMachine's process monitoring API. Currently supported using kqueue for OSX/BSD.
+  # EventMachine's process monitoring API. On Mac OS X and *BSD this method is implemented using kqueue.
   #
-  # === Usage example:
+  # @example
   #
   #  module ProcessWatcher
   #    def process_exited
@@ -1233,11 +1243,13 @@ module EventMachine
   #
   #  pid = fork{ sleep }
   #
-  #  EM.run{
-  #    EM.watch_process(pid, ProcessWatcher)
-  #    EM.add_timer(1){ Process.kill('TERM', pid) }
+  #  EventMachine.run {
+  #    EventMachine.watch_process(pid, ProcessWatcher)
+  #    EventMachine.add_timer(1){ Process.kill('TERM', pid) }
   #  }
   #
+  # @param [Integer]       pid     PID of the process to watch.
+  # @param [Class, Module] handler A class or module that implements event handlers associated with the file.
   def self.watch_process(pid, handler=nil, *args)
     pid = pid.to_i
 
@@ -1254,10 +1266,13 @@ module EventMachine
 
   # Catch-all for errors raised during event loop callbacks.
   #
-  #  EM.error_handler{ |e|
-  #    puts "Error raised during event loop: #{e.message}"
-  #  }
+  # @example
   #
+  #   EventMachine.error_handler{ |e|
+  #     puts "Error raised during event loop: #{e.message}"
+  #   }
+  #
+  # @param [#call] cb Global catch-all errback
   def self.error_handler cb = nil, &blk
     if cb or blk
       @error_handler = cb || blk
@@ -1266,12 +1281,12 @@ module EventMachine
     end
   end
 
-  # enable_proxy allows for direct writing of incoming data back out to another descriptor, at the C++ level in the reactor.
-  # This is especially useful for proxies where high performance is required. Propogating data from a server response
+  # This method allows for direct writing of incoming data back out to another descriptor, at the C++ level in the reactor.
+  # This is very efficient and especially useful for proxies where high performance is required. Propogating data from a server response
   # all the way up to Ruby, and then back down to the reactor to be sent back to the client, is often unnecessary and
   # incurs a significant performance decrease.
   #
-  # The two arguments are Connections, 'from' and 'to'. 'from' is the connection whose inbound data you want
+  # The two arguments are instance of {EventMachine::Connection} subclasses, 'from' and 'to'. 'from' is the connection whose inbound data you want
   # relayed back out. 'to' is the connection to write it to.
   #
   # Once you call this method, the 'from' connection will no longer get receive_data callbacks from the reactor,
@@ -1279,10 +1294,10 @@ module EventMachine
   # in the example, that proxy_target_unbound will be called when this occurs. After that, further incoming
   # data will be passed into receive_data as normal.
   #
-  # Note also that this feature supports different types of descriptors - TCP, UDP, and pipes. You can relay
-  # data from one kind to another.
+  # Note also that this feature supports different types of descriptors: TCP, UDP, and pipes. You can relay
+  # data from one kind to another, for example, feed a pipe from a UDP stream.
   #
-  # Example:
+  # @example
   #
   #  module ProxyConnection
   #    def initialize(client, request)
@@ -1310,42 +1325,55 @@ module EventMachine
   #    def receive_data(data)
   #      (@buf ||= "") << data
   #      if @buf =~ /\r\n\r\n/ # all http headers received
-  #        EM.connect("10.0.0.15", 80, ProxyConnection, self, data)
+  #        EventMachine.connect("10.0.0.15", 80, ProxyConnection, self, data)
   #      end
   #    end
   #  end
   #
-  #  EM.run {
-  #    EM.start_server("127.0.0.1", 8080, ProxyServer)
+  #  EventMachine.run {
+  #    EventMachine.start_server("127.0.0.1", 8080, ProxyServer)
   #  }
+  #
+  # @param [EventMachine::Connection] from    Source of data to be proxies/streamed.
+  # @param [EventMachine::Connection] to      Destination of data to be proxies/streamed.
+  # @param [Integer]                  bufsize Buffer size to use
+  # @param [Integer]                  length  Maximum number of bytes to proxy.
+  #
+  # @see EventMachine.disable_proxy
   def self.enable_proxy(from, to, bufsize=0, length=0)
     EM::start_proxy(from.signature, to.signature, bufsize, length)
   end
 
-  # disable_proxy takes just one argument, a Connection that has proxying enabled via enable_proxy.
+  # Takes just one argument, a {Connection} that has proxying enabled via {EventMachine.enable_proxy}.
   # Calling this method will remove that functionality and your connection will begin receiving
-  # data via receive_data again.
+  # data via {Connection#receive_data} again.
+  #
+  # @param [EventMachine::Connection] from    Source of data that is being proxied
+  # @see EventMachine.enable_proxy
   def self.disable_proxy(from)
     EM::stop_proxy(from.signature)
   end
 
   # Retrieve the heartbeat interval. This is how often EventMachine will check for dead connections
-  # that have had an InactivityTimeout set via Connection#set_comm_inactivity_timeout.
+  # that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}.
   # Default is 2 seconds.
+  #
+  # @return [Integer] Heartbeat interval, in seconds
   def self.heartbeat_interval
     EM::get_heartbeat_interval
   end
 
   # Set the heartbeat interval. This is how often EventMachine will check for dead connections
-  # that have had an InactivityTimeout set via Connection#set_comm_inactivity_timeout.
+  # that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}.
   # Takes a Numeric number of seconds. Default is 2.
-  def self.heartbeat_interval= (time)
+  #
+  # @param [Integer] time Heartbeat interval, in seconds
+  def self.heartbeat_interval=(time)
     EM::set_heartbeat_interval time.to_f
   end
 
-  private
-
-  def self.event_callback conn_binding, opcode, data # :nodoc:
+  # @private
+  def self.event_callback conn_binding, opcode, data
     #
     # Changed 27Dec07: Eliminated the hookable error handling.
     # No one was using it, and it degraded performance significantly.
@@ -1363,7 +1391,11 @@ module EventMachine
     if opcode == ConnectionUnbound
       if c = @conns.delete( conn_binding )
         begin
-          c.unbind
+          if c.original_method(:unbind).arity == 1
+            c.unbind(data == 0 ? nil : EventMachine::ERRNOS[data])
+          else
+            c.unbind
+          end
         rescue
           @wrapped_exception = $!
           stop
@@ -1385,9 +1417,9 @@ module EventMachine
       @conns[data] = c
       blk and blk.call(c)
       c # (needed?)
-    ##
-    # The remaining code is a fallback for the pure ruby and java reactors.
-    # In the C++ reactor, these events are handled in the C event_callback() in rubymain.cpp
+      ##
+      # The remaining code is a fallback for the pure ruby and java reactors.
+      # In the C++ reactor, these events are handled in the C event_callback() in rubymain.cpp
     elsif opcode == ConnectionCompleted
       c = @conns[conn_binding] or raise ConnectionNotBound, "received ConnectionCompleted for unknown signature: #{conn_binding}"
       c.connection_completed
@@ -1410,107 +1442,10 @@ module EventMachine
     end
   end
 
-  #--
-  # The original event_callback below handled runtime errors in ruby and degraded performance significantly.
-  # An optional C-based error handler is now available via EM::error_handler
-  #
-  # private
-  # def EventMachine::original_event_callback conn_binding, opcode, data
-  #   #
-  #   # Added 03Oct07: Any code path that invokes user-written code must
-  #   # wrap itself in a begin/rescue for RuntimeErrors, that calls the
-  #   # user-overridable class method #handle_runtime_error.
-  #   #
-  #   if opcode == ConnectionData
-  #     c = @conns[conn_binding] or raise ConnectionNotBound
-  #     begin
-  #       c.receive_data data
-  #     rescue
-  #       EventMachine.handle_runtime_error
-  #     end
-  #   elsif opcode == ConnectionUnbound
-  #     if c = @conns.delete( conn_binding )
-  #       begin
-  #         c.unbind
-  #       rescue
-  #         EventMachine.handle_runtime_error
-  #       end
-  #     elsif c = @acceptors.delete( conn_binding )
-  #       # no-op
-  #     else
-  #       raise ConnectionNotBound
-  #     end
-  #   elsif opcode == ConnectionAccepted
-  #     accep,args,blk = @acceptors[conn_binding]
-  #     raise NoHandlerForAcceptedConnection unless accep
-  #     c = accep.new data, *args
-  #     @conns[data] = c
-  #     begin
-  #       blk and blk.call(c)
-  #     rescue
-  #       EventMachine.handle_runtime_error
-  #     end
-  #     c # (needed?)
-  #   elsif opcode == TimerFired
-  #     t = @timers.delete( data ) or raise UnknownTimerFired
-  #     begin
-  #       t.call
-  #     rescue
-  #       EventMachine.handle_runtime_error
-  #     end
-  #   elsif opcode == ConnectionCompleted
-  #     c = @conns[conn_binding] or raise ConnectionNotBound
-  #     begin
-  #       c.connection_completed
-  #     rescue
-  #       EventMachine.handle_runtime_error
-  #     end
-  #   elsif opcode == LoopbreakSignalled
-  #     begin
-  #     run_deferred_callbacks
-  #     rescue
-  #       EventMachine.handle_runtime_error
-  #     end
-  #   end
-  # end
-  #
-  #
-  # # Default handler for RuntimeErrors that are raised in user code.
-  # # The default behavior is to re-raise the error, which ends your program.
-  # # To override the default behavior, re-implement this method in your code.
-  # # For example:
-  # #
-  # #  module EventMachine
-  # #    def self.handle_runtime_error
-  # #      $>.puts $!
-  # #    end
-  # #  end
-  # #
-  # #--
-  # # We need to ensure that any code path which invokes user code rescues RuntimeError
-  # # and calls this method. The obvious place to do that is in #event_callback,
-  # # but, scurrilously, it turns out that we need to be finer grained that that.
-  # # Periodic timers, in particular, wrap their invocations of user code inside
-  # # procs that do other stuff we can't not do, like schedule the next invocation.
-  # # This is a potential non-robustness, since we need to remember to hook in the
-  # # error handler whenever and wherever we change how user code is invoked.
-  # #
-  # def EventMachine::handle_runtime_error
-  #   @runtime_error_hook ? @runtime_error_hook.call : raise
-  # end
-  #
-  # # Sets a handler for RuntimeErrors that are raised in user code.
-  # # Pass a block with no parameters. You can also call this method without a block,
-  # # which restores the default behavior (see #handle_runtime_error).
-  # #
-  # def EventMachine::set_runtime_error_hook &blk
-  #   @runtime_error_hook = blk
-  # end
-
-  #--
-  # This is a provisional implementation of a stream-oriented file access object.
-  # We also experiment with wrapping up some better exception reporting.
-  def self._open_file_for_writing filename, handler=nil # :nodoc:
+  #
+  #
+  # @private
+  def self._open_file_for_writing filename, handler=nil
     klass = klass_from_handler(Connection, handler)
 
     s = _write_file filename
@@ -1520,7 +1455,7 @@ module EventMachine
     c
   end
 
-  private
+  # @private
   def self.klass_from_handler(klass = Connection, handler = nil, *args)
     klass = if handler and handler.is_a?(Class)
       raise ArgumentError, "must provide module or subclass of #{klass.name}" unless klass >= handler
@@ -1545,6 +1480,7 @@ module EventMachine
   end
 end # module EventMachine
 
-# Save everyone some typing.
+# Alias for {EventMachine}
 EM = EventMachine
+# Alias for {EventMachine::Protocols}
 EM::P = EventMachine::Protocols