Ticket #10424: documenting_cattr_accessors.rb

# Currently a whole bunch of Rails config options aren't documented. This is due to RDoc not picking up comments on cattr_accessor. Here's a bit of a look at the options.
#
# Run rdoc over it to read the docs and see the results of the different options.
#
# Tim Lucas <t.lucas@toolmantim.com>

require 'rubygems'
gem 'activesupport'
require 'activesupport'

class Class
  # Defines a class attribute accessor method and sets the class attribute's
  # default by calling the class attribute writer method, such as <tt>self.option=</tt>.
  #
  # The class attribute writer method must be defined before calling this method.
  #
  # Without this convience method you'd typically do:
  #   class Mailer
  #     # Sets whether to perform deliveries of outgoing mail
  #     def self.perform_deliveries=(perform_deliveries)
  #       @@perform_deliveries = perform_deliveries
  #     end
  #     def self.perform_deliveries
  #       @@perform_deliveries
  #     end
  #     @@perform_deliveries = true
  #   end
  #
  # The equivalent to the above code but using cattr_reader_with_default is:
  #   class Mailer
  #     # Sets whether to perform deliveries of outgoing mail
  #     def self.perform_deliveries=(perform_deliveries)
  #       @@perform_deliveries = perform_deliveries
  #     end
  #     cattr_reader_with_default :perform_deliveries, true
  #   end
  def cattr_reader_with_default(sym, default)
    cattr_reader sym
    class_eval(<<-EOS, __FILE__, __LINE__)
      self.#{sym} = default
    EOS
  end
end

# Currently a whole bunch of Rails config options aren't documented. This is due to RDoc not picking up comments on <tt>cattr_accessor</tt>.
#
# Some common examples might be <tt>ActionView::Base.field_error_proc</tt> and <tt>ActiveRecord::Base.colorize_logging</tt> which currently are only documented via the source, blogs and google.
#
# Possible solutions:
# * Move the comment from the <tt>cattr_accessor</tt> into an rdoc "Configuration" section on Base
#   * Lose the connection between code+comment (bad for maintenance)
#   * The cattr_accessor may be defined in any extension module so documentation is very far from its source code
#   * This is the approach for <tt>ActionMailer</tt> but it works because its mostly in the one file
# * Copy + paste the comment from the <tt>cattr_accessor</tt> into an rdoc "Configuration" section on Base
#   * Copy + paste is bad
#   * The cattr_accessor may be defined in any extension module so documentation is very far from its source code
# * Patch RDoc to pick up cattr_accessor comments
# * Use class/module writer and reader methods and manually set default
#   * RDoc documents both config option readers and writers
#   * Bloaty
#   * e.g. ClassWriterAndReaderMethods
# * Use class/module writer and some convenenience method
#   * RDoc only documents config option writers
#   * e.g. ClassWriterAndAttrConvenienceMethod
# * Leave them as is (i.e. using an RDoc above <tt>cattr_accessor</tt>)
#   * Everything stays undocumented );
#   * e.g. AttributeAccessors
#
# Considering most config options are now using <tt>instance_writer => false</tt> its probably a good time for a refactoring
module ActiveSupportConfigDocsDemo
  # The current way of documenting config options.
  #
  # The ultimate in minimalism, though we all have to suffer for it.
  class AttributeAccessors
    # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
    # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
    # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
    # that this is a global setting for all Active Records.
    cattr_accessor :primary_key_prefix_type, :instance_writer => false
    @@primary_key_prefix_type = nil
  
    # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
    # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
    # for tables in a shared database. By default, the prefix is the empty string.
    cattr_accessor :table_name_prefix, :instance_writer => false
    @@table_name_prefix = ""
  
    # Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
    # "people_basecamp"). By default, the suffix is the empty string.
    cattr_accessor :table_name_suffix, :instance_writer => false
    @@table_name_suffix = ""
  
    # Indicates whether table names should be the pluralized versions of the corresponding class names.
    # If true, the default table name for a +Product+ class will be +products+. If false, it would just be +product+.
    # See table_name for the full rules on table/class naming. This is true, by default.
    cattr_accessor :pluralize_table_names, :instance_writer => false
    @@pluralize_table_names = true
  end

  # A straight ruby way of specifying config options.
  #
  # It's pretty darn bloaty, though it has the advantage of both writer and reader methods getting picked up by RDoc.
  class ClassWriterAndReaderMethods
    class << self
      # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
      # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
      # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
      # that this is a global setting for all Active Records.
      def primary_key_prefix_type=(primary_key_prefix_type)
        @@primary_key_prefix_type = primary_key_prefix_type
      end
      def primary_key_prefix_type
        @@primary_key_prefix_type
      end
      @@primary_key_prefix_type = nil

      # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
      # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
      # for tables in a shared database. By default, the prefix is the empty string.
      def table_name_prefix=(table_name_prefix)
        @@table_name_prefix = table_name_prefix
      end
      def table_name_prefix
        @@table_name_prefix
      end
      @@table_name_prefix = ""

      # Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
      # "people_basecamp"). By default, the suffix is the empty string.
      def table_name_suffix=(table_name_suffix)
        @@table_name_suffix = table_name_suffix
      end
      def table_name_suffix
        @@table_name_suffix
      end
      @@table_name_suffix = ""

      # Indicates whether table names should be the pluralized versions of the corresponding class names.
      # If true, the default table name for a +Product+ class will be +products+. If false, it would just be +product+.
      # See table_name for the full rules on table/class naming. This is true, by default.
      def pluralize_table_names=(pluralize_table_names)
        @@pluralize_table_names = pluralize_table_names
      end
      def pluralize_table_names
        @@pluralize_table_names
      end
      @@pluralize_table_names = true
    end
  end

  # Using standard Ruby to declaring option writers and Class.cattr_reader_with_default to specify the reader method and default value.
  #
  # At least 5 times sexier than the ClassWriterAndReaderMethods approach.
  class ClassWriterAndAttrConvenienceMethod
    # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
    # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
    # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
    # that this is a global setting for all Active Records.
    def self.primary_key_prefix_type=(primary_key_prefix_type)
      @@primary_key_prefix_type = primary_key_prefix_type
    end
    cattr_reader_with_default :primary_key_prefix_type, nil

    # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
    # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
    # for tables in a shared database. By default, the prefix is the empty string.
    def self.table_name_prefix=(table_name_prefix)
      @@table_name_prefix = table_name_prefix
    end
    cattr_reader_with_default :table_name_prefix, ""

    # Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
    # "people_basecamp"). By default, the suffix is the empty string.
    def self.table_name_suffix=(table_name_suffix)
      @@table_name_suffix = table_name_suffix
    end
    cattr_reader_with_default :table_name_suffix, ""

    # Indicates whether table names should be the pluralized versions of the corresponding class names.
    # If true, the default table name for a +Product+ class will be +products+. If false, it would just be +product+.
    # See table_name for the full rules on table/class naming. This is true, by default.
    def self.pluralize_table_names=(pluralize_table_names)
      @@pluralize_table_names = pluralize_table_names
    end
    cattr_reader_with_default :pluralize_table_names, true
  end
end
  
if $0 == __FILE__
  require 'test/unit'
  class SomeClass #:nodoc:
    def self.option=(option)
      @@option = option
    end
    cattr_reader_with_default :option, "Value"
  end
  class CAttrReaderWithDefaultTest < Test::Unit::TestCase #:nodoc:
    def test_should_create_and_accessor_and_set_the_default
      assert_equal "Value", SomeClass.option
    end
  end
end