Misc docs

config/setup.rb

@@ -22,10 +22,9 @@
   # end
 
   # And any other code here that will be run before the client, e.g:
-  
+
   # HelloWorld.register!
   # DebugHandler.register!
-
-  RawConnectionLogger.register!
+  #RawConnectionLogger.register!
 
 end

lib/marvin.rb

@@ -39,8 +39,12 @@ module Marvin
 
   end
 
-  def self.version(include_minor = false)
-    VERSION[0, (include_minor ? 4 : 3)].join(".")
+  # Returns a string of the current version,
+  # optionally including a build number.
+  # @param [Boolean] include_build include a build version in the string
+  def self.version(include_build = nil)
+    include_build = VERSION[3].to_i == 0 if version_build.nil?
+    VERSION[0, (include_build ? 4 : 3)].join(".")
   end
 
   has_library :util, :abstract_client, :abstract_parser, :irc, :exception_tracker

lib/marvin/abstract_client.rb

@@ -1,6 +1,14 @@
 require "marvin/irc/event"
 
 module Marvin
+  # An abstract class implementing (and mixing in) a lot of
+  # the default functionality involved on handling an irc
+  # connection.
+  #
+  # To provide an implementation, you must subclass and implement
+  # #send_line, .add_reconnect, and any other loader etc methods.
+  #
+  # @see Marvin::IRC::Client
   class AbstractClient
 
     is :dispatchable, :loggable
@@ -29,6 +37,9 @@ def initialize(opts)
     # current connection, dispatching a :client_connected event
     # once it has finished. During this process, it will
     # call #client= on each handler if they respond to it.
+    #
+    # @see Marvin::AbstractClient.setup
+    # @see Marvin::Base#client=
     def process_connect
       self.class.setup
       logger.info "Initializing the current instance"
@@ -38,47 +49,71 @@ def process_connect
       dispatch :client_connected
     end
 
+    # Handles a lost connection / disconnect, stopping the loader if it's the
+    # last connection (purposely terminated) otherwise scheduling a reconnection
+    #
+    # @see Marvin::Loader.stop!
     def process_disconnect
       logger.info "Handling disconnect for #{host_with_port}"
       connections.delete(self)
       dispatch :client_disconnected
-      unless @disconnect_expected
+      if @disconnect_expected
+        Marvin::Loader.stop! if connections.blank?
+      else
         logger.warn "Unexpectly lost connection to server; adding reconnect"
         self.class.add_reconnect @connection_config
-      else
-        Marvin::Loader.stop! if connections.blank?
       end
     end
 
+    # Iterates over handles and calls client= when defined. Used before dispatching
+    # in order to ensure each hander has the correct client. Note that this needs
+    # to be improved soon.
     def setup_handlers
       handlers.each { |h| h.client = self if h.respond_to?(:client=) }
     end
 
+    # If @@development is true, We'll attempt to reload any changed files (namely,
+    # handlers).s
     def process_development
       Marvin::Reloading.reload! if @@development
     end
 
+    # Before dispatching, check if we need to reload and setup handlers correctly.
     def pre_dispatching
       process_development
+      setup_handlers
     end
 
-    # Sets the current class-wide settings of this IRC Client
-    # to either an OpenStruct or the results of #to_hash on
-    # any other value that is passed in.
+    # Sets the current class-wide settings of this IRC Client to
+    # an instance of Marvin::Nash with the properties of a hash
+    # / nash passed in.
+    #
+    # The new configuration will be normalized before use (namely,
+    # it will convert nested items to nashes)
+    #
+    # @param [Marvin::Nash, Hash] config the new configuration
     def self.configuration=(config)
       config = Marvin::Nash.new(config.to_hash) unless config.is_a?(Marvin::Nash)
       @@configuration = config.normalized
     end
 
+    # Check if if the cient class has been setup yet
+    # @return [Boolean] is the client class setup
     def self.setup?
       @setup ||= false
     end
 
+    # Conditional configure
     def self.setup
       return if setup?
       configure
     end
 
+    # Configure the class - namely, merge the app-wide configuration
+    # and if given a block, merge the results in.
+    #
+    # @yieldparam [Marvin::Nash] an empty nash
+    # @yieldreturn [Marvin::Nash] any changed settings.
     def self.configure
       config = Marvin::Nash.new
       config.merge! Marvin::Settings.configuration
@@ -87,33 +122,45 @@ def self.configure
         config.merge! nash
       end
       @@configuration = config
-      # Help is only currently available on an instance running
-      # distributed handler.
+      # Help is only currently available on an instance NOT running the distributed handler.
       Marvin::CoreCommands.register! unless Marvin::Distributed::Handler.registered?
       @setup = true
     end
 
     ## Handling all of the the actual client stuff.
 
+    # Receives a raw line (without EOL characters) and dispatch the
+    # incoming_line event. Once that's done, parse the line and
+    # dispatch an event if present.
+    #
+    # @param [String] line the incoming line
     def receive_line(line)
-      setup_handlers
       dispatch :incoming_line, :line => line
       event = Marvin::Settings.parser.parse(line)
       dispatch(event.to_incoming_event_name, event.to_hash) unless event.nil?  
     end
 
+    # Returns a list of default channels to join on connect
+    # @return [Array<String>] an array of channel names that are joined on connect
     def default_channels
       @default_channels ||= []
     end
 
+    # Sets the list of default channels to join
+    # @param [Array<String>] channels the array of channel names
     def default_channels=(channels)
       @default_channels = channels.to_a.map { |c| c.to_s }
     end
 
+    # Returns the irc server and port
+    # @return [String] server port in "server:port" format
     def host_with_port
       @host_with_port ||= "#{server}:#{port}"
     end
 
+    # Returns a list available nicks / nicks to try
+    # on connect.
+    # @return [Array<String>] The array of nicks
     def nicks
       if @nicks.blank? && !@nicks_loaded
         logger.info "Setting default nick list"

lib/marvin/abstract_parser.rb

@@ -1,4 +1,5 @@
 module Marvin
+  # Abstract Class for implementing abstract parsers.
   class AbstractParser
 
     attr_accessor :line, :command, :event
@@ -15,6 +16,8 @@ def to_event
       @event
     end
 
+    # Parses a line and return the associated event.
+    # @return [Marvin::IRC:Event] the parsed event
     def self.parse(line)
       new(line.strip).to_event
     end

lib/marvin/irc/client.rb

@@ -167,7 +167,6 @@ def normalize_connection_options(config)
     # Registers a callback handle that will be periodically run.
     def periodically(timing, event_callback)
       EventMachine.add_periodic_timer(timing) do
-        setup_handlers
         dispatch(event_callback.to_sym)
       end
     end