Permalink
Browse files

update AS docs [ci skip]

  • Loading branch information...
1 parent c1c9f1c commit d71d5ba71fadf4219c466c0332f78f6e325bcc6c Francesco Rodriguez committed Sep 17, 2012
@@ -1,30 +1,38 @@
module ActiveSupport
- # 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.
+ # 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.
#
- # 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.
+ # 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.
#
# bc = BacktraceCleaner.new
# bc.add_filter { |line| line.gsub(Rails.root, '') }
# 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.
+ # 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 have 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)
@@ -38,25 +46,27 @@ def clean(backtrace, kind = :silent)
end
end
- # Adds a filter from the block provided. Each line in the backtrace will be mapped against this filter.
+ # Adds a filter from the block provided. Each line in the backtrace will be
+ # mapped against this filter.
#
# # Will turn "/my/rails/root/app/models/person.rb" into "/app/models/person.rb"
# backtrace_cleaner.add_filter { |line| line.gsub(Rails.root, '') }
def add_filter(&block)
@filters << block
end
- # Adds a silencer from the block provided. If the silencer returns true for a given line, it will 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.
#
# # Will reject all lines that include the word "mongrel", like "/gems/mongrel/server.rb" or "/app/my_mongrel_server/rb"
# backtrace_cleaner.add_silencer { |line| line =~ /mongrel/ }
def add_silencer(&block)
@silencers << 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 one of the libraries you use.
+ # 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 one of
+ # the libraries you use.
def remove_silencers!
@silencers = []
end
@@ -3,30 +3,33 @@
module ActiveSupport
module Benchmarkable
- # Allows you to measure the execution time of a block in a template and records the result to
- # the log. Wrap this block around expensive operations or possible bottlenecks to get a time
- # reading for the operation. For example, let's say you thought your file processing method
- # was taking too long; you could wrap it in a benchmark block.
+ # Allows you to measure the execution time of a block in a template and
+ # records the result to the log. Wrap this block around expensive operations
+ # or possible bottlenecks to get a time reading for the operation. For
+ # example, let's say you thought your file processing method was taking too
+ # long; you could wrap it in a benchmark block.
#
- # <% benchmark "Process data files" do %>
+ # <% benchmark 'Process data files' do %>
# <%= expensive_files_operation %>
# <% end %>
#
- # That would add something like "Process data files (345.2ms)" to the log, which you can then
- # use to compare timings when optimizing your code.
+ # That would add something like "Process data files (345.2ms)" to the log,
+ # which you can then use to compare timings when optimizing your code.
#
- # You may give an optional logger level (:debug, :info, :warn, :error) as the :level option.
- # The default logger level value is :info.
+ # You may give an optional logger level (<tt>:debug</tt>, <tt>:info</tt>,
+ # <tt>:warn</tt>, <tt>:error</tt>) as the <tt>:level</tt> option. The
+ # default logger level value is <tt>:info</tt>.
#
- # <% benchmark "Low-level files", :level => :debug do %>
+ # <% benchmark 'Low-level files', level: :debug do %>
# <%= lowlevel_files_operation %>
# <% end %>
#
- # Finally, you can pass true as the third argument to silence all log activity (other than the
- # timing information) from inside the block. This is great for boiling down a noisy block to
- # just a single statement that produces one log line:
+ # Finally, you can pass true as the third argument to silence all log
+ # activity (other than the timing information) from inside the block. This
+ # is great for boiling down a noisy block to just a single statement that
+ # produces one log line:
#
- # <% benchmark "Process data files", :level => :info, :silence => true do %>
+ # <% benchmark 'Process data files', level: :info, silence: true do %>
# <%= expensive_and_chatty_files_operation %>
# <% end %>
def benchmark(message = "Benchmarking", options = {})
@@ -44,7 +47,6 @@ def benchmark(message = "Benchmarking", options = {})
end
# Silence the logger during the execution of the block.
- #
def silence
old_logger_level, logger.level = logger.level, ::Logger::ERROR if logger
yield
Oops, something went wrong.

0 comments on commit d71d5ba

Please sign in to comment.