Permalink
Browse files

move example code to be above reconfiguring discussion; add clarity a…

…bout silencers and filters; misc grammar changes - for backtrace cleaners
  • Loading branch information...
mjankowski committed Jun 22, 2011
1 parent 98623a0 commit 32de3b8119fcf82f7f89a78d64db93751c06b0a8
Showing with 16 additions and 11 deletions.
  1. +16 −11 activesupport/lib/active_support/backtrace_cleaner.rb
@@ -1,12 +1,12 @@
module ActiveSupport
- # Many backtraces include too much information that's not relevant for the context. This makes it hard to find the signal
- # in the backtrace and adds debugging time. With a BacktraceCleaner, you can setup filters and silencers for your particular
- # context, so only the relevant lines are included.
+ # Backtraces often include many lines that are not relevant for the context under review. This makes it hard to find the
+ # signal amongst the backtrace noise, and adds debugging time. With a BacktraceCleaner, filters and silencers are used to
+ # remove the noisy lines, so that only the most relevant lines remain.
#
- # If you need to reconfigure an existing BacktraceCleaner, like the one in Rails, to show as much as possible, you can always
- # call BacktraceCleaner#remove_silencers! Also, if you need to reconfigure an existing BacktraceCleaner so that it does not
- # filter or modify the paths of any lines of the backtrace, you can call BacktraceCleaner#remove_filters! These two methods
- # will give you a completely untouched backtrace.
+ # Filters are used to modify lines of data, while silencers are used to remove lines entirely. The typical filter use case
+ # is to remove lengthy path information from the start of each line, and view file paths relevant to the app directory
+ # instead of the file system root. The typical silencer use case is to exclude the output of a noisy library from the
+ # backtrace, so that you can focus on the rest.
#
# ==== Example:
#
@@ -15,13 +15,18 @@ module ActiveSupport
# bc.add_silencer { |line| line =~ /mongrel|rubygems/ }
# bc.clean(exception.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems
#
+ # To reconfigure an existing BacktraceCleaner (like the default one in Rails) and show as much data as possible, you can
+ # always call <tt>BacktraceCleaner#remove_silencers!</tt>, which will restore the backtrace to a pristine state. If you
+ # need to reconfigure an existing BacktraceCleaner so that it does not filter or modify the paths of any lines of the
+ # backtrace, you can call BacktraceCleaner#remove_filters! These two methods will give you a completely untouched backtrace.
+ #
# Inspired by the Quiet Backtrace gem by Thoughtbot.
class BacktraceCleaner
def initialize
@filters, @silencers = [], []
end
- # Returns the backtrace after all filters and silencers has been run against it. Filters run first, then silencers.
+ # Returns the backtrace after all filters and silencers have been run against it. Filters run first, then silencers.
def clean(backtrace, kind = :silent)
filtered = filter(backtrace)
@@ -45,8 +50,8 @@ def add_filter(&block)
@filters << block
end
- # Adds a silencer from the block provided. If the silencer returns true for a given line, it'll be excluded from the
- # clean backtrace.
+ # Adds a silencer from the block provided. If the silencer returns true for a given line, it will be excluded from
+ # the clean backtrace.
#
# Example:
#
@@ -57,7 +62,7 @@ def add_silencer(&block)
end
# Will remove all silencers, but leave in the filters. This is useful if your context of debugging suddenly expands as
- # you suspect a bug in the libraries you use.
+ # you suspect a bug in one of the libraries you use.
def remove_silencers!
@silencers = []
end

0 comments on commit 32de3b8

Please sign in to comment.