Permalink
Browse files

Starting YARD'ing up the plugin

  • Loading branch information...
qrush authored and Joe Ferris committed Aug 20, 2009
1 parent 14a2c3e commit c4e26cbeaca5c408e55398ab8277215f746a066e
Showing with 72 additions and 72 deletions.
  1. +2 −0 .gitignore
  2. +40 −46 README → README.rdoc
  3. +7 −9 Rakefile
  4. +23 −17 lib/hoptoad_notifier.rb
View
@@ -8,3 +8,5 @@ public/system
coverage/*
rdoc/
tags
+.yardoc
+doc
View
@@ -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.
-
View
@@ -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
View
@@ -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?

0 comments on commit c4e26cb

Please sign in to comment.