Skip to content
This repository
Browse code

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

…bout silencers and filters; misc grammar changes - for backtrace cleaners
  • Loading branch information...
commit eaee931f5d8db83eb4b994299c323547bfb5a195 1 parent 6d4e3f3
Matt Jankowski authored June 22, 2011 fxn committed June 23, 2011
27  activesupport/lib/active_support/backtrace_cleaner.rb
... ...
@@ -1,12 +1,12 @@
1 1
 module ActiveSupport
2  
-  # Many backtraces include too much information that's not relevant for the context. This makes it hard to find the signal
3  
-  # in the backtrace and adds debugging time. With a BacktraceCleaner, you can setup filters and silencers for your particular
4  
-  # context, so only the relevant lines are included.
  2
+  # Backtraces often include many lines that are not relevant for the context under review. This makes it hard to find the 
  3
+  # signal amongst the backtrace noise, and adds debugging time. With a BacktraceCleaner, filters and silencers are used to
  4
+  # remove the noisy lines, so that only the most relevant lines remain.
5 5
   #
6  
-  # If you need to reconfigure an existing BacktraceCleaner, like the one in Rails, to show as much as possible, you can always
7  
-  # call BacktraceCleaner#remove_silencers! Also, if you need to reconfigure an existing BacktraceCleaner so that it does not
8  
-  # filter or modify the paths of any lines of the backtrace, you can call BacktraceCleaner#remove_filters! These two methods
9  
-  # will give you a completely untouched backtrace.
  6
+  # Filters are used to modify lines of data, while silencers are used to remove lines entirely.  The typical filter use case
  7
+  # is to remove lengthy path information from the start of each line, and view file paths relevant to the app directory 
  8
+  # instead of the file system root.  The typical silencer use case is to exclude the output of a noisy library from the 
  9
+  # backtrace, so that you can focus on the rest.
10 10
   #
11 11
   # ==== Example:
12 12
   #
@@ -15,13 +15,18 @@ module ActiveSupport
15 15
   #   bc.add_silencer { |line| line =~ /mongrel|rubygems/ }
16 16
   #   bc.clean(exception.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems
17 17
   #
  18
+  # To reconfigure an existing BacktraceCleaner (like the default one in Rails) and show as much data as possible, you can 
  19
+  # always call <tt>BacktraceCleaner#remove_silencers!</tt>, which will restore the backtrace to a pristine state.  If you 
  20
+  # need to reconfigure an existing BacktraceCleaner so that it does not filter or modify the paths of any lines of the 
  21
+  # backtrace, you can call BacktraceCleaner#remove_filters! These two methods will give you a completely untouched backtrace.
  22
+  #
18 23
   # Inspired by the Quiet Backtrace gem by Thoughtbot.
19 24
   class BacktraceCleaner
20 25
     def initialize
21 26
       @filters, @silencers = [], []
22 27
     end
23 28
 
24  
-    # Returns the backtrace after all filters and silencers has been run against it. Filters run first, then silencers.
  29
+    # Returns the backtrace after all filters and silencers have been run against it. Filters run first, then silencers.
25 30
     def clean(backtrace, kind = :silent)
26 31
       filtered = filter(backtrace)
27 32
 
@@ -45,8 +50,8 @@ def add_filter(&block)
45 50
       @filters << block
46 51
     end
47 52
 
48  
-    # Adds a silencer from the block provided. If the silencer returns true for a given line, it'll be excluded from the
49  
-    # clean backtrace.
  53
+    # Adds a silencer from the block provided. If the silencer returns true for a given line, it will be excluded from 
  54
+    # the clean backtrace.
50 55
     #
51 56
     # Example:
52 57
     #
@@ -57,7 +62,7 @@ def add_silencer(&block)
57 62
     end
58 63
 
59 64
     # Will remove all silencers, but leave in the filters. This is useful if your context of debugging suddenly expands as
60  
-    # you suspect a bug in the libraries you use.
  65
+    # you suspect a bug in one of the libraries you use.
61 66
     def remove_silencers!
62 67
       @silencers = []
63 68
     end

0 notes on commit eaee931

Please sign in to comment.
Something went wrong with that request. Please try again.