complete rewrite of the documentation of AS::PerThreadRegistry

* It focuses on how to use it.

* Removes some ambigueties in the original docs about whether the state is stored in the class.

* Documents it provides class-level accessors via method_missing.

* Documents that if the extended class has an initializer, it must accept no arguments.

activerecord/lib/active_record/runtime_registry.rb

 require 'active_support/per_thread_registry'
 
 module ActiveRecord
-  # This is a registry class for storing local variables in active record. The
+  # This is a registry class for storing local variables in Active Record. The
   # class allows you to access variables that are local to the current thread.
   # These thread local variables are stored as attributes in the
   # +RuntimeRegistry+ class.

activesupport/lib/active_support/per_thread_registry.rb

 module ActiveSupport
-  # This module creates a local registry class inside each thread. It provides
-  # basic methods which will store thread locals in a single class. This
-  # prevents the proliferation of too many thread locals and allows you to
-  # explicitly keep track of each of the variables you're using as thread
-  # locals in a class which includes this module.
+  # This module is used to encapsulate access to thread local variables.
   #
-  # For example, instead of using a bunch of different thread locals to keep
-  # track of some variables like so:
+  # Given
   #
-  #   Thread.current[:active_record_connection_handler] = connection_handler
-  #   Thread.current[:active_record_sql_runtime]        = sql_runtime
+  #   module ActiveRecord
+  #     class RuntimeRegistry
+  #       extend ActiveSupport::PerThreadRegistry
   #
-  # You could use the following class which implements the +PerThreadRegistry+
-  # module:
+  #       attr_accessor :connection_handler
+  #     end
+  #   end
   #
-  #   class NewRegistry
-  #     extend ActiveSupport::PerThreadRegistry
+  # <tt>ActiveRecord::RuntimeRegistry</tt> gets an +instance+ class method
+  # that returns an instance of the class unique to the current thread. Thus,
+  # instead of polluting +Thread.current+
   #
-  #     attr_accessor :connection_handler, :sql_runtime
-  #   end
+  #   Thread.current[:connection_handler]
+  #
+  # you write
+  #
+  #   ActiveRecord::RuntimeRegistry.instance.connection_handler
+  #
+  # A +method_missing+ handler that proxies to the thread local instance is
+  # installed in the extended class so the call above can be shortened to
+  #
+  #   ActiveRecord::RuntimeRegistry.connection_handler
   #
-  #   NewRegistry.instance.connection_handler = connection_handler
-  #   NewRegistry.instance.sql_runtime        = sql_runtime
+  # The instance is stored as a thread local keyed by the name of the class,
+  # that is the string "ActiveRecord::RuntimeRegistry" in the example above.
   #
-  # The new way of keeping track of the thread locals will create a new local
-  # inside of +Thread.current+ with a key which is the name of the extended
-  # class. Now you can easily access per thread variables by just calling the
-  # variable name on the registry.
+  # If the class has an initializer, it must accept no arguments.
   module PerThreadRegistry
     def instance
       Thread.current[self.name] ||= new