Starting YARD'ing up the plugin

.gitignore

@@ -8,3 +8,5 @@ public/system
 coverage/*
 rdoc/
 tags
+.yardoc
+doc

README → README.rdoc

@@ -1,33 +1,31 @@
-HoptoadNotifier
-===============
+= HoptoadNotifier
 
 This is the notifier plugin for integrating apps with Hoptoad.
 
 When an uncaught exception occurs, HoptoadNotifier will POST the relevant data 
 to the Hoptoad server specified in your environment.
 
-INSTALLATION
-------------
+== Installation
 
-REMOVE EXCEPTION_NOTIFIER
+=== Remove exception_notifier
 
-In your ApplicationController, REMOVE this line:
+in your ApplicationController, REMOVE this line:
 
   include ExceptionNotifiable
 
 In your config/environment* files, remove all references to ExceptionNotifier
 
 Remove the vendor/plugins/exception_notifier directory.
 
-INSTALL HOPTOAD_NOTIFIER
+=== Install hoptoad_notifier
 
-From your project's RAILS_ROOT, run:
+from your project's RAILS_ROOT, run:
 
   script/plugin install git://github.com/thoughtbot/hoptoad_notifier.git
 
-CONFIGURATION
+=== Configuration
 
-You should have something like this in config/initializers/hoptoad.rb.
+you should have something like this in config/initializers/hoptoad.rb.
 
   HoptoadNotifier.configure do |config|
     config.api_key = '1234567890abcdef'
@@ -46,7 +44,8 @@ be aggregated, filtered, sorted, analyzed, massaged, and searched. In previous
 releases you had to include HoptoadNotifier::Catcher into your
 ApplicationController, but the plugin takes care of that now.
 
-** NOTE FOR RAILS 1.2.* USERS: **
+*NOTE FOR RAILS 1.2.* USERS:*
+
 You will need to copy the hoptoad_notifier_tasks.rake file into your
 RAILS_ROOT/lib/tasks directory in order for the following to work:
 
@@ -58,10 +57,9 @@ this rake task (from RAILS_ROOT):
 If everything is configured properly, that task will send a notice to hoptoad 
 which will be visible immediately.
 
-USAGE
------
+== Usage
 
-For the most part, hoptoad works for itself.  Once you've included the notifier 
+for the most part, hoptoad works for itself.  Once you've included the notifier 
 in your ApplicationController (which is now done automatically by the plugin), 
 all errors will be rescued by the #rescue_action_in_public provided by the plugin.
 
@@ -80,62 +78,61 @@ analysis.
 
 To perform custom error processing after Hoptoad has been notified, define the instance method #rescue_action_in_public_without_hoptoad(exception) in your controller.
 
-TRACKING DEPLOYMENTS IN HOPTOAD
--------------------------------
+== Tracking deployments in hoptoad
 
-Paying Hoptoad plans support the ability to track deployments of your application in Hoptoad.
+paying Hoptoad plans support the ability to track deployments of your application in Hoptoad.
 By notifying Hoptoad of your application deployments, all errors are resolved when a deploy occurs,
 so that you'll be notified again about any errors that reoccur after a deployment.
 
 Additionally, it's possible to review the errors in Hoptoad that occurred before and after a deploy.
 
 When Hoptoad is installed as a plugin this functionality is loaded automatically (if you have Capistrano version 2.0.0 or greater).
 
-When Hoptoad installed as a gem, you need to add 
+When Hoptoad installed as a gem, you need to add
+
   require 'hoptoad_notifier/recipes/hoptoad'
+
 to your deploy.rb
 
-GOING BEYOND EXCEPTIONS
------------------------
+== Going beyond exceptions
 
 You can also pass a hash to notify_hoptoad method and store whatever you want, not just an exception. And you can also use it anywhere, not just in controllers:
 
-  begin 
-    params = { 
+  begin
+    params = {
       # params that you pass to a method that can throw an exception 
     }
-    my_unpredicable_method(params) 
+    my_unpredicable_method(params)
   rescue => e
     HoptoadNotifier.notify(
-      :error_class => "Special Error", 
-      :error_message => "Special Error: #{e.message}", 
+      :error_class => "Special Error",
+      :error_message => "Special Error: #{e.message}",
       :request => { :params => params }
     )
   end
 
 While in your controllers you use the notify_hoptoad method, anywhere else in your code, use HoptoadNotifier.notify. Hoptoad will get all the information about the error itself. As for a hash, these are the keys you should pass:
 
-  * :error_class – Use this to group similar errors together. When Hoptoad catches an exception it sends the class name of that exception object.
-  * :error_message – This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
-  * :request – While there are several ways to send additional data to Hoptoad, passing a Hash with :params key as :request as in the example above is the most common use case. When Hoptoad catches an exception in a controller, the actual HTTP client request is being sent using this key.
+* :error_class – Use this to group similar errors together. When Hoptoad catches an exception it sends the class name of that exception object.
+* :error_message – This is the title of the error you see in the errors list. For exceptions it is "#{exception.class.name}: #{exception.message}"
+* :request – While there are several ways to send additional data to Hoptoad, passing a Hash with :params key as :request as in the example above is the most common use case. When Hoptoad catches an exception in a controller, the actual HTTP client request is being sent using this key.
 
 Hoptoad merges the hash you pass with these default options:
 
   def default_notice_options
-    { 
-      :api_key => HoptoadNotifier.api_key, 
-      :error_message => 'Notification', 
-      :backtrace => caller, 
-      :request => {}, 
-      :session => {}, 
-      :environment => ENV.to_hash 
-    } 
+    {
+      :api_key => HoptoadNotifier.api_key,
+      :error_message => 'Notification',
+      :backtrace => caller,
+      :request => {},
+      :session => {},
+      :environment => ENV.to_hash
+    }
   end
 
 You can override any of those parameters.
 
-FILTERING
----------
+== Filtering
 
 You can specify a whitelist of errors, that Hoptoad will not report on.  Use 
 this feature when you are so apathetic to certain errors that you don't want 
@@ -145,6 +142,7 @@ This filter will only be applied to automatic notifications, not manual
 notifications (when #notify is called directly).
 
 Hoptoad ignores the following exceptions by default:
+
   ActiveRecord::RecordNotFound
   ActionController::RoutingError
   ActionController::InvalidAuthenticityToken
@@ -198,8 +196,7 @@ To replace sensitive information sent to the hoptoad service with [FILTERED] use
     config.params_filters << "credit_card_number"
   end
 
-TESTING
--------
+== Testing
 
 When you run your tests, you might notice that the hoptoad service is recording
 notices generated using #notify when you don't expect it to.  You can 
@@ -212,10 +209,9 @@ errors are not reported while running tests.
     end
   end
 
-SUPPORTED RAILS VERSIONS
-------------------------
+== Supported rails versions
 
-The notifier currently supports the following versions of Rails:
+the notifier currently supports the following versions of Rails:
 
 * 1.2.6
 * 2.0.2
@@ -226,8 +222,6 @@ The notifier currently supports the following versions of Rails:
 
 Please open up a support ticket on Tender ( http://help.hoptoadapp.com ) if you're using a version of Rails that is not listed above and the notifier is not working properly.
 
-THANKS
-------
+== Thanks
 
 Thanks to Eugene Bolshakov for the excellent write-up on GOING BEYOND EXCEPTIONS, which we have included above.
-

Rakefile

@@ -12,19 +12,17 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-desc 'Generate documentation for the hoptoad_notifier plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'HoptoadNotifier'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 desc 'Run ginger tests'
 task :ginger do
   $LOAD_PATH << File.join(*%w[vendor ginger lib])
   ARGV.clear
   ARGV << 'test'
   load File.join(*%w[vendor ginger bin ginger])
 end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+  end
+rescue LoadError
+end

lib/hoptoad_notifier.rb

@@ -20,40 +20,42 @@ module HoptoadNotifier
   }
 
   class << self
-    # (Internal)
     # The sender object is responsible for delivering formatted data to the Hoptoad server.
     # Must respond to #send_to_hoptoad. See HoptoadNotifier::Sender.
     attr_accessor :sender
 
-    # (Internal)
     # A Hoptoad configuration object. Must act like a hash and return sensible
-    # values for all Hoptoad configuration options. See
-    # HoptoadNotifier::Configuration.
+    # values for all Hoptoad configuration options. See HoptoadNotifier::Configuration.
     attr_accessor :configuration
 
+    # Tell the log that the Notifier is good to go
     def report_ready
       write_verbose_log("Notifier #{VERSION} ready to catch errors")
     end
 
+    # Prints out the environment info to the log for debugging help
     def report_environment_info
       write_verbose_log("Environment Info: #{environment_info}")
     end
 
+    # Prints out the response body from Hoptoad for debugging help
     def report_response_body(response)
       write_verbose_log("Response from Hoptoad: \n#{response}")
     end
 
+    # Returns the Ruby version, Rails version, and current Rails environment
     def environment_info
       info = "[Ruby: #{RUBY_VERSION}]"
       info << " [Rails: #{::Rails::VERSION::STRING}]" if defined?(Rails)
       info << " [Env: #{configuration.environment_name}]"
     end
 
+    # Writes out the given message to the #logger
     def write_verbose_log(message)
       logger.info LOG_PREFIX + message if logger
     end
 
-    # Checking for the logger in hopes we can get rid of the ugly syntax someday
+    # Look for the Rails logger currently defined
     def logger
       if defined?(Rails.logger)
         Rails.logger
@@ -63,11 +65,11 @@ def logger
     end
 
     # Call this method to modify defaults in your initializers.
-    #
-    # HoptoadNotifier.configure do |config|
-    #   config.api_key = '1234567890abcdef'
-    #   config.secure  = false
-    # end
+    # @example
+    #   HoptoadNotifier.configure do |config|
+    #     config.api_key = '1234567890abcdef'
+    #     config.secure  = false
+    #   end
     def configure
       self.configuration ||= Configuration.new
       yield(configuration)
@@ -78,17 +80,21 @@ def configure
     # You can send an exception manually using this method, even when you are not in a
     # controller. You can pass an exception or a hash that contains the attributes that
     # would be sent to Hoptoad:
-    # * api_key: The API key for this project. The API key is a unique identifier that Hoptoad
-    #   uses for identification.
-    # * error_message: The error returned by the exception (or the message you want to log).
-    # * backtrace: A backtrace, usually obtained with +caller+.
-    # * request: The controller's request object.
-    # * session: The contents of the user's session.
-    # * environment: ENV merged with the contents of the request's environment.
+    #
+    # @param [Exception] exception The exception you want to notify Hoptoad about.
+    # @param [Hash] opts Data that will be sent to Hoptoad.
+    # @option opts [String] :api_key The API key for this project. The API key is a unique identifier that Hoptoad uses for identification.
+    # @option opts [String] :error_message The error returned by the exception (or the message you want to log).
+    # @option opts [String] :backtrace A backtrace, usually obtained with +caller+.
+    # @option opts [String] :request The controller's request object.
+    # @option opts [String] :session The contents of the user's session.
+    # @option opts [String] :environment ENV merged with the contents of the request's environment.
     def notify(exception, opts = {})
       send_notice(build_notice_for(exception, opts))
     end
 
+    # Sends the notice unless it is one of the default ignored exceptions
+    # @see HoptoadNotifier.notify
     def notify_or_ignore(exception, opts = {})
       notice = build_notice_for(exception, opts)
       send_notice(notice) unless notice.ignore?