Permalink
Browse files

Fleshing out more docs

  • Loading branch information...
1 parent 5b6c57b commit 5e7a896242e01a5efb026b0c353866b98303d175 @qrush qrush committed with Joe Ferris Aug 21, 2009
View
@@ -65,6 +65,7 @@ def logger
end
# Call this method to modify defaults in your initializers.
+ #
# @example
# HoptoadNotifier.configure do |config|
# config.api_key = '1234567890abcdef'
@@ -77,9 +78,7 @@ def configure
report_ready
end
- # 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:
+ # Sends an exception manually using this method, even when you are not in a controller.
#
# @param [Exception] exception The exception you want to notify Hoptoad about.
# @param [Hash] opts Data that will be sent to Hoptoad.
@@ -1,6 +1,8 @@
module HoptoadNotifier
+ # Front end to parsing the backtrace for each notice
class Backtrace
+ # Handles backtrace parsing line by line
class Line
INPUT_FORMAT = %r{^([^:]+):(\d+)(?::in `([^']+)')?$}.freeze
@@ -14,6 +16,9 @@ class Line
# The method of the line (such as index)
attr_reader :method
+ # Parses a single line of a given backtrace
+ # @param [String] unparsed_line The raw line from +caller+ or some backtrace
+ # @return [Line] The parsed backtrace line
def self.parse(unparsed_line)
_, file, number, method = unparsed_line.match(INPUT_FORMAT).to_a
new(file, number, method)
@@ -25,6 +30,7 @@ def initialize(file, number, method)
self.method = method
end
+ # Reconstructs the line in a readable fashion
def to_s
"#{file}:#{number}:in `#{method}'"
end
@@ -42,6 +48,7 @@ def inspect
attr_writer :file, :number, :method
end
+ # holder for an Array of Backtrace::Line instances
attr_reader :lines
def self.parse(ruby_backtrace, opts = {})
@@ -2,6 +2,7 @@ module HoptoadNotifier
# Include this module in Controllers in which you want to be notified of errors.
module Catcher
+ # Sets up an alias chain to catch exceptions when Rails does
def self.included(base) #:nodoc:
if base.instance_methods.map(&:to_s).include? 'rescue_action_in_public' and !base.instance_methods.map(&:to_s).include? 'rescue_action_in_public_without_hoptoad'
base.send(:alias_method, :rescue_action_in_public_without_hoptoad, :rescue_action_in_public)
@@ -130,33 +130,50 @@ def initialize
# Takes a block and adds it to the list of backtrace filters. When the filters
# run, the block will be handed each line of the backtrace and can modify
- # it as necessary. For example, by default a path matching the RAILS_ROOT
- # constant will be transformed into "[RAILS_ROOT]"
+ # it as necessary.
+ #
+ # @example
+ # config.filter_bracktrace do |line|
+ # line.gsub(/^#{Rails.root}/, "[RAILS_ROOT]")
+ # end
+ #
+ # @param [Proc] block The new backtrace filter.
+ # @yieldparam [String] line A line in the backtrace.
def filter_backtrace(&block)
self.backtrace_filters << block
end
- # Takes a block and adds it to the list of ignore filters. When the filters
- # run, the block will be handed the exception. If the block yields a value
- # equivalent to "true," the exception will be ignored, otherwise it will be
- # processed by hoptoad.
+ # Takes a block and adds it to the list of ignore filters.
+ # When the filters run, the block will be handed the exception.
+ # @example
+ # config.ignore_by_filter do |exception_data|
+ # true if exception_data[:error_class] == "RuntimeError"
+ # end
+ #
+ # @param [Proc] block The new ignore filter
+ # @yieldparam [Hash] data The exception data given to +HoptoadNotifier.notify+
+ # @yieldreturn [Boolean] If the block returns true the exception will be ignored, otherwise it will be processed by hoptoad.
def ignore_by_filter(&block)
self.ignore_by_filters << block
end
- # Sets the list of ignored errors to only what is passed in here. This method
- # can be passed a single error or a list of errors.
+ # Overrides the list of default ignored errors.
+ #
+ # @param [Array<Exception>] names A list of exceptions to ignore.
def ignore_only=(names)
@ignore = [names].flatten
end
- # Sets the list of ignored user agents to only what is passed in here. This method
- # can be passed a single user agent or a list of user agents.
+ # Overrides the list of default ignored user agents
+ #
+ # @param [Array<String>] A list of user agents to ignore
def ignore_user_agent_only=(names)
@ignore_user_agent = [names].flatten
end
# Allows config options to be read like a hash
+ #
+ # @param [Symbol] option Key for a given attribute
def [](option)
send(option)
end
@@ -169,11 +186,14 @@ def to_hash
end
# Returns a hash of all configurable options merged with +hash+
+ #
+ # @param [Hash] hash A set of configuration options that will take precedence over the defaults
def merge(hash)
to_hash.merge(hash)
end
- # Returns false if in a development environment, false otherwise.
+ # Determines if the notifier will send notices.
+ # @return [Boolean] Returns +false+ if in a development environment, +true+ otherwise.
def public?
!development_environments.include?(environment_name)
end
@@ -102,6 +102,7 @@ def initialize(args)
clean_environment
end
+ # Converts the given notice to XML
def to_xml
builder = Builder::XmlMarkup.new
builder.instruct!
@@ -152,13 +153,18 @@ def to_xml
xml.to_s
end
+ # Determines if this notice should be ignored
def ignore?
ignored_class_names.include?(error_class) ||
ignore_by_filters.any? {|filter| filter.call(self) }
end
- # Allows properties to be accessed using a hash-like syntax, such as:
+ # Allows properties to be accessed using a hash-like syntax
+ #
+ # @example
# notice[:error_message]
+ # @param [String] method The given key for an attribute
+ # @return The attribute value, or self if given +:request+
def [](method)
case method
when :request
@@ -1,19 +1,20 @@
module HoptoadNotifier
+ # Sends out the notice to Hoptoad
class Sender
NOTICES_URI = '/api/v2/notices/'.freeze
- attr_reader :proxy_host, :proxy_port, :proxy_user, :proxy_pass, :protocol,
- :host, :port, :secure, :http_open_timeout, :http_read_timeout
-
def initialize(options = {})
[:proxy_host, :proxy_port, :proxy_user, :proxy_pass, :protocol,
:host, :port, :secure, :http_open_timeout, :http_read_timeout].each do |option|
instance_variable_set("@#{option}", options[option])
end
end
- def send_to_hoptoad(data) #:nodoc:
+ # Sends the notice data off to Hoptoad for processing.
+ #
+ # @param [String] data The XML notice to be sent off
+ def send_to_hoptoad(data)
http =
Net::HTTP::Proxy(proxy_host, proxy_port, proxy_user, proxy_pass).
new(url.host, url.port)
@@ -39,7 +40,10 @@ def send_to_hoptoad(data) #:nodoc:
private
- def url #:nodoc:
+ attr_reader :proxy_host, :proxy_port, :proxy_user, :proxy_pass, :protocol,
+ :host, :port, :secure, :http_open_timeout, :http_read_timeout
+
+ def url
URI.parse("#{protocol}://#{host}:#{port}").merge(NOTICES_URI)
end
View
@@ -2,7 +2,17 @@
require 'uri'
require 'active_support'
+# Capistrano tasks for notifying Hoptoad of deploys
module HoptoadTasks
+
+ # Alerts Hoptoad of a deploy.
+ #
+ # @param [Hash] opts Data about the deploy that is set to Hoptoad
+ #
+ # @option opts [String] :rails_env Environment of the deploy (production, staging)
+ # @option opts [String] :scm_revision The given revision/sha that is being deployed
+ # @option opts [String] :scm_repository Address of your repository to help with code lookups
+ # @option opts [String] :local_username Who is deploying
def self.deploy(opts = {})
if HoptoadNotifier.configuration.api_key.blank?
puts "I don't seem to be configured with an API key. Please check your configuration."

0 comments on commit 5e7a896

Please sign in to comment.