More Subscriber and LogSubscriber doc uniformity

attach_to was previously [improved][1] to allow defining methods after
attaching instead of having to attach after all methods have been
defined. The docs for Subscriber were [updated][2], but LogSubscriber
docs were not.

This commit copies the attach_to doc changes from Subscriber to
LogSubscriber. In addition, there are other improvements to linking and
applying the monospace formatting that were present in one of Subscriber
or LogSubscriber and are now applied to both. The final change is
updating the description of how flush_all! is used, because its usage
has [changed][3] since this doc was written.

[1]: 3408857
[2]: 25b3f73
[3]: 378464a

Author: skipkayhil

activesupport/lib/active_support/log_subscriber.rb

@@ -18,26 +18,20 @@ module ActiveSupport
   #
   #   module ActiveRecord
   #     class LogSubscriber < ActiveSupport::LogSubscriber
+  #       attach_to :active_record
+  #
   #       def sql(event)
   #         info "#{event.payload[:name]} (#{event.duration}) #{event.payload[:sql]}"
   #       end
   #     end
   #   end
   #
-  # And it's finally registered as:
-  #
-  #   ActiveRecord::LogSubscriber.attach_to :active_record
-  #
-  # Since we need to know all instance methods before attaching the log
-  # subscriber, the line above should be called after your
-  # <tt>ActiveRecord::LogSubscriber</tt> definition.
-  #
-  # A logger also needs to be set with <tt>ActiveRecord::LogSubscriber.logger=</tt>.
-  # This is assigned automatically in a Rails environment.
+  # ActiveRecord::LogSubscriber.logger must be set as well, but it is assigned
+  # automatically in a \Rails environment.
   #
-  # After configured, whenever a <tt>"sql.active_record"</tt> notification is published,
-  # it will properly dispatch the event
-  # (<tt>ActiveSupport::Notifications::Event</tt>) to the sql method.
+  # After configured, whenever a <tt>"sql.active_record"</tt> notification is
+  # published, it will properly dispatch the event
+  # (ActiveSupport::Notifications::Event) to the +sql+ method.
   #
   # Being an ActiveSupport::Notifications consumer,
   # <tt>ActiveSupport::LogSubscriber</tt> exposes a simple interface to check if
@@ -62,9 +56,10 @@ module ActiveSupport
   #     end
   #   end
   #
-  # Log subscriber also has some helpers to deal with logging and automatically
-  # flushes all logs when the request finishes
-  # (via <tt>action_dispatch.callback</tt> notification) in a Rails environment.
+  # <tt>ActiveSupport::LogSubscriber</tt> also has some helpers to deal with
+  # logging. For example, ActiveSupport::LogSubscriber.flush_all! will ensure
+  # that all logs are flushed, and it is called in Rails::Rack::Logger after a
+  # request finishes.
   class LogSubscriber < Subscriber
     # Embed in a String to clear all previous ANSI sequences.
     CLEAR = ActiveSupport::Deprecation::DeprecatedObjectProxy.new("\e[0m", "CLEAR is deprecated! Use MODES[:clear] instead.", ActiveSupport.deprecator)

activesupport/lib/active_support/subscriber.rb

@@ -5,7 +5,7 @@
 module ActiveSupport
   # = Active Support \Subscriber
   #
-  # ActiveSupport::Subscriber is an object set to consume
+  # <tt>ActiveSupport::Subscriber</tt> is an object set to consume
   # ActiveSupport::Notifications. The subscriber dispatches notifications to
   # a registered object based on its given namespace.
   #
@@ -22,9 +22,9 @@ module ActiveSupport
   #     end
   #   end
   #
-  # After configured, whenever a "sql.active_record" notification is published,
-  # it will properly dispatch the event (ActiveSupport::Notifications::Event) to
-  # the +sql+ method.
+  # After configured, whenever a <tt>"sql.active_record"</tt> notification is
+  # published, it will properly dispatch the event
+  # (ActiveSupport::Notifications::Event) to the +sql+ method.
   #
   # We can detach a subscriber as well:
   #