diff --git a/actionpack/lib/action_view/base.rb b/actionpack/lib/action_view/base.rb index 4d06ca0d89..a7ba9f374a 100644 --- a/actionpack/lib/action_view/base.rb +++ b/actionpack/lib/action_view/base.rb @@ -8,11 +8,13 @@ module ActionView #:nodoc: class NonConcattingString < ActiveSupport::SafeBuffer end + # = Action View Base + # # Action View templates can be written in three ways. If the template file has a .erb (or .rhtml) extension then it uses a mixture of ERb # (included in Ruby) and HTML. If the template file has a .builder (or .rxml) extension then Jim Weirich's Builder::XmlMarkup library is used. # If the template file has a .rjs extension then it will use ActionView::Helpers::PrototypeHelper::JavaScriptGenerator. # - # = ERb + # == ERb # # You trigger ERb by using embeddings such as <% %>, <% -%>, and <%= %>. The <%= %> tag set is used when you want output. Consider the # following loop for names: @@ -32,7 +34,7 @@ class NonConcattingString < ActiveSupport::SafeBuffer # # <%- and -%> suppress leading and trailing whitespace, including the trailing newline, and can be used interchangeably with <% and %>. # - # == Using sub templates + # === Using sub templates # # Using sub templates allows you to sidestep tedious replication and extract common display structures in shared templates. The # classic example is the use of a header and footer (even though the Action Pack-way would be to use Layouts): @@ -54,7 +56,7 @@ class NonConcattingString < ActiveSupport::SafeBuffer # #
and. # If the object cannot be converted to YAML using +to_yaml+, +inspect+ will be called instead. diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 9e2448fe97..a8887a804e 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -7,6 +7,7 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Form Helpers module Helpers # Form helpers are designed to make working with resources much easier # compared to using vanilla HTML. diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb index 6bf78647ec..c564d30302 100644 --- a/actionpack/lib/action_view/helpers/form_options_helper.rb +++ b/actionpack/lib/action_view/helpers/form_options_helper.rb @@ -4,6 +4,7 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Form Option Helpers module Helpers # Provides a number of methods for turning different kinds of containers into a set of option tags. # == Options diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index 0727375fc0..ea491b2db8 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -4,6 +4,7 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Form Tag Helpers module Helpers # Provides a number of methods for creating form tags that doesn't rely on an Active Record object assigned to the template like # FormHelper does. Instead, you provide the names and values manually. diff --git a/actionpack/lib/action_view/helpers/javascript_helper.rb b/actionpack/lib/action_view/helpers/javascript_helper.rb index b0a7718f22..84f53b842c 100644 --- a/actionpack/lib/action_view/helpers/javascript_helper.rb +++ b/actionpack/lib/action_view/helpers/javascript_helper.rb @@ -1,6 +1,7 @@ require 'action_view/helpers/tag_helper' module ActionView + # = Action View JavaScript Helpers module Helpers # Provides functionality for working with JavaScript in your views. # diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb index a798c3eaef..3038b07143 100644 --- a/actionpack/lib/action_view/helpers/prototype_helper.rb +++ b/actionpack/lib/action_view/helpers/prototype_helper.rb @@ -4,6 +4,7 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Prototype Helpers module Helpers # Prototype[http://www.prototypejs.org/] is a JavaScript library that provides # DOM[http://en.wikipedia.org/wiki/Document_Object_Model] manipulation, diff --git a/actionpack/lib/action_view/helpers/raw_output_helper.rb b/actionpack/lib/action_view/helpers/raw_output_helper.rb index 8c7f41177d..da7599fa8f 100644 --- a/actionpack/lib/action_view/helpers/raw_output_helper.rb +++ b/actionpack/lib/action_view/helpers/raw_output_helper.rb @@ -1,6 +1,15 @@ module ActionView #:nodoc: + # = Action View Raw Output Helper module Helpers #:nodoc: module RawOutputHelper + # This method outputs without escaping a string. Since escaping tags is + # now default, this can be used when you don't want Rails to automatically + # escape tags. This is not recommended if the data is coming from the user's + # input. + # + # For example: + # + # <%=raw @user.name %> def raw(stringish) stringish.to_s.html_safe end diff --git a/actionpack/lib/action_view/helpers/record_tag_helper.rb b/actionpack/lib/action_view/helpers/record_tag_helper.rb index a9cf15f418..7433f08777 100644 --- a/actionpack/lib/action_view/helpers/record_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/record_tag_helper.rb @@ -1,4 +1,5 @@ module ActionView + # = Action View Record Tag Helpers module Helpers module RecordTagHelper # Produces a wrapper DIV element with id and class parameters that diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb index f173523f6a..b47818a22a 100644 --- a/actionpack/lib/action_view/helpers/sanitize_helper.rb +++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb @@ -2,19 +2,25 @@ require 'action_view/helpers/tag_helper' module ActionView + # = Action View Sanitize Helpers module Helpers #:nodoc: # The SanitizeHelper module provides a set of methods for scrubbing text of undesired HTML elements. # These helper methods extend Action View making them callable within your template files. module SanitizeHelper - # This +sanitize+ helper will html encode all tags and strip all attributes that aren't specifically allowed. - # It also strips href/src tags with invalid protocols, like javascript: especially. It does its best to counter any - # tricks that hackers may use, like throwing in unicode/ascii/hex values to get past the javascript: filters. Check out + # This +sanitize+ helper will html encode all tags and strip all attributes that + # aren't specifically allowed. + # + # It also strips href/src tags with invalid protocols, like javascript: especially. + # It does its best to counter any tricks that hackers may use, like throwing in + # unicode/ascii/hex values to get past the javascript: filters. Check out # the extensive test suite. # # <%= sanitize @article.body %> # - # You can add or remove tags/attributes if you want to customize it a bit. See ActionView::Base for full docs on the - # available options. You can add tags/attributes for single uses of +sanitize+ by passing either the :attributes or :tags options: + # You can add or remove tags/attributes if you want to customize it a bit. + # See ActionView::Base for full docs on the available options. You can add + # tags/attributes for single uses of +sanitize+ by passing either the + # :attributes or :tags options: # # Normal Use # diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb index 37319cca1b..7f7776e9c0 100644 --- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb +++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb @@ -2,9 +2,11 @@ require 'active_support/json' module ActionView + # = Action View Scriptaculous Helpers module Helpers - # Provides a set of helpers for calling Scriptaculous JavaScript - # functions, including those which create Ajax controls and visual effects. + # Provides a set of helpers for calling Scriptaculous[http://script.aculo.us/] + # JavaScript functions, including those which create Ajax controls and visual + # effects. # # To be able to use these helpers, you must include the Prototype # JavaScript framework and the Scriptaculous JavaScript library in your @@ -12,6 +14,7 @@ module Helpers # for more information on including the necessary JavaScript. # # The Scriptaculous helpers' behavior can be tweaked with various options. + # # See the documentation at http://script.aculo.us for more information on # using these helpers in your application. module ScriptaculousHelper diff --git a/actionpack/lib/action_view/helpers/tag_helper.rb b/actionpack/lib/action_view/helpers/tag_helper.rb index 66277f79fe..d4e8b3d587 100644 --- a/actionpack/lib/action_view/helpers/tag_helper.rb +++ b/actionpack/lib/action_view/helpers/tag_helper.rb @@ -2,6 +2,7 @@ require 'set' module ActionView + # = Action View Tag Helpers module Helpers #:nodoc: # Provides methods to generate HTML tags programmatically when you can't use # a Builder. By default, they output XHTML compliant tags. diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index ccc9156777..9afa989453 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -3,6 +3,7 @@ require 'action_view/helpers/tag_helper' module ActionView + # = Action View Text Helpers module Helpers #:nodoc: # The TextHelper module provides a set of methods for filtering, formatting # and transforming strings, which can reduce the amount of inline Ruby code in diff --git a/actionpack/lib/action_view/helpers/translation_helper.rb b/actionpack/lib/action_view/helpers/translation_helper.rb index 0c8829b0b8..dac9c28ab7 100644 --- a/actionpack/lib/action_view/helpers/translation_helper.rb +++ b/actionpack/lib/action_view/helpers/translation_helper.rb @@ -1,21 +1,28 @@ require 'action_view/helpers/tag_helper' module ActionView + # = Action View Translation Helpers module Helpers module TranslationHelper - # Delegates to I18n#translate but also performs three additional functions. First, it'll catch MissingTranslationData exceptions - # and turn them into inline spans that contains the missing key, such that you can see in a view what is missing where. + # Delegates to I18n#translate but also performs three additional functions. + # First, it'll catch MissingTranslationData exceptions and turn them into + # inline spans that contains the missing key, such that you can see in a + # view what is missing where. # - # Second, it'll scope the key by the current partial if the key starts with a period. So if you call translate(".foo") from the - # people/index.html.erb template, you'll actually be calling I18n.translate("people.index.foo"). This makes it less repetitive - # to translate many keys within the same partials and gives you a simple framework for scoping them consistently. If you don't - # prepend the key with a period, nothing is converted. + # Second, it'll scope the key by the current partial if the key starts + # with a period. So if you call translate(".foo") from the + # people/index.html.erb template, you'll actually be calling + # I18n.translate("people.index.foo"). This makes it less repetitive + # to translate many keys within the same partials and gives you a simple framework + # for scoping them consistently. If you don't prepend the key with a period, + # nothing is converted. # - # Third, it'll mark the translation as safe HTML if the key has the suffix "_html" or the last element of the key is the word - # "html". For example, calling translate("footer_html") or translate("footer.html") will return a safe HTML string that won't - # be escaped by other HTML helper methods. This naming convention helps to identify translations that include HTML tags so that + # Third, it'll mark the translation as safe HTML if the key has the suffix + # "_html" or the last element of the key is the word "html". For example, + # calling translate("footer_html") or translate("footer.html") will return + # a safe HTML string that won't be escaped by other HTML helper methods. This + # naming convention helps to identify translations that include HTML tags so that # you know what kind of output to expect when you call translate in a template. - def translate(key, options = {}) translation = I18n.translate(scope_key_by_partial(key), options.merge!(:raise => true)) if html_safe_translation_key?(key) && translation.respond_to?(:html_safe) diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb index 210f148c02..bcfa6a68d7 100644 --- a/actionpack/lib/action_view/helpers/url_helper.rb +++ b/actionpack/lib/action_view/helpers/url_helper.rb @@ -4,6 +4,7 @@ require 'action_dispatch' module ActionView + # = Action View URL Helpers module Helpers #:nodoc: # Provides a set of methods for making links and getting URLs that # depend on the routing subsystem (see ActionDispatch::Routing). diff --git a/actionpack/lib/action_view/lookup_context.rb b/actionpack/lib/action_view/lookup_context.rb index 823226cb9c..3ea8b86af1 100644 --- a/actionpack/lib/action_view/lookup_context.rb +++ b/actionpack/lib/action_view/lookup_context.rb @@ -2,6 +2,8 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Lookup Context + # # LookupContext is the object responsible to hold all information required to lookup # templates, i.e. view paths and details. The LookupContext is also responsible to # generate a key, given to view paths, used in the resolver cache lookup. Since diff --git a/actionpack/lib/action_view/paths.rb b/actionpack/lib/action_view/paths.rb index 7f5e5d11b8..9857d688d2 100644 --- a/actionpack/lib/action_view/paths.rb +++ b/actionpack/lib/action_view/paths.rb @@ -1,4 +1,5 @@ module ActionView #:nodoc: + # = Action View PathSet class PathSet < Array #:nodoc: %w(initialize << concat insert push unshift).each do |method| class_eval <<-METHOD, __FILE__, __LINE__ + 1 diff --git a/actionpack/lib/action_view/railtie.rb b/actionpack/lib/action_view/railtie.rb index c606a71e18..e8ea15f47c 100644 --- a/actionpack/lib/action_view/railtie.rb +++ b/actionpack/lib/action_view/railtie.rb @@ -2,6 +2,7 @@ require "rails" module ActionView + # = Action View Railtie class Railtie < Rails::Railtie config.action_view = ActiveSupport::OrderedOptions.new diff --git a/actionpack/lib/action_view/render/layouts.rb b/actionpack/lib/action_view/render/layouts.rb index 1f837b37e2..a474783a20 100644 --- a/actionpack/lib/action_view/render/layouts.rb +++ b/actionpack/lib/action_view/render/layouts.rb @@ -1,4 +1,5 @@ module ActionView + # = Action View Layouts module Layouts # Returns the contents that are yielded to a layout, given a name or a block. # diff --git a/actionpack/lib/action_view/render/partials.rb b/actionpack/lib/action_view/render/partials.rb index 85f67d4f14..a2c191c580 100644 --- a/actionpack/lib/action_view/render/partials.rb +++ b/actionpack/lib/action_view/render/partials.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/object/blank' module ActionView + # = Action View Partials + # # There's also a convenience method for rendering sub templates within the current controller that depends on a # single object (we call this kind of sub templates for partials). It relies on the fact that partials should # follow the naming convention of being prefixed with an underscore -- as to separate them from regular diff --git a/actionpack/lib/action_view/render/rendering.rb b/actionpack/lib/action_view/render/rendering.rb index 4d35296932..cb39621d6b 100644 --- a/actionpack/lib/action_view/render/rendering.rb +++ b/actionpack/lib/action_view/render/rendering.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/object/try' module ActionView + # Action View Rendering module Rendering # Returns the result of a render that's dictated by the options hash. The primary options are: # diff --git a/actionpack/lib/action_view/template.rb b/actionpack/lib/action_view/template.rb index 53ad24fdc6..c00557209b 100644 --- a/actionpack/lib/action_view/template.rb +++ b/actionpack/lib/action_view/template.rb @@ -3,6 +3,7 @@ require 'active_support/core_ext/kernel/singleton_class' module ActionView + # = Action View Template class Template extend ActiveSupport::Autoload diff --git a/activerecord/lib/active_record/associations/association_collection.rb b/activerecord/lib/active_record/associations/association_collection.rb index d9903243ce..5b5094bcab 100644 --- a/activerecord/lib/active_record/associations/association_collection.rb +++ b/activerecord/lib/active_record/associations/association_collection.rb @@ -3,6 +3,8 @@ module ActiveRecord module Associations + # = Active Record Association Collection + # # AssociationCollection is an abstract class that provides common stuff to # ease the implementation of association proxies that represent # collections. See the class hierarchy in AssociationProxy. diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb index e88618d278..f333f4d603 100644 --- a/activerecord/lib/active_record/associations/association_proxy.rb +++ b/activerecord/lib/active_record/associations/association_proxy.rb @@ -2,6 +2,8 @@ module ActiveRecord module Associations + # = Active Record Associations + # # This is the root class of all association proxies: # # AssociationProxy diff --git a/activerecord/lib/active_record/associations/belongs_to_association.rb b/activerecord/lib/active_record/associations/belongs_to_association.rb index d2f2267e5c..c2a6495db5 100644 --- a/activerecord/lib/active_record/associations/belongs_to_association.rb +++ b/activerecord/lib/active_record/associations/belongs_to_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Associations module Associations class BelongsToAssociation < AssociationProxy #:nodoc: def create(attributes = {}) diff --git a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb index f6edd6383c..38454ec242 100644 --- a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb +++ b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Polymorphic Association module Associations class BelongsToPolymorphicAssociation < AssociationProxy #:nodoc: def replace(record) diff --git a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb index 7f39a189e4..c989c3536d 100644 --- a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb +++ b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Has And Belongs To Many Association module Associations class HasAndBelongsToManyAssociation < AssociationCollection #:nodoc: def create(attributes = {}) diff --git a/activerecord/lib/active_record/associations/has_many_association.rb b/activerecord/lib/active_record/associations/has_many_association.rb index 0464e8ceea..92c6b3e770 100644 --- a/activerecord/lib/active_record/associations/has_many_association.rb +++ b/activerecord/lib/active_record/associations/has_many_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Has Many Association module Associations # This is the proxy that handles a has many association. # diff --git a/activerecord/lib/active_record/associations/has_many_through_association.rb b/activerecord/lib/active_record/associations/has_many_through_association.rb index 5338bb099d..17f850756f 100644 --- a/activerecord/lib/active_record/associations/has_many_through_association.rb +++ b/activerecord/lib/active_record/associations/has_many_through_association.rb @@ -2,6 +2,7 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Has Many Through Association module Associations class HasManyThroughAssociation < HasManyAssociation #:nodoc: include ThroughAssociationScope diff --git a/activerecord/lib/active_record/associations/has_one_association.rb b/activerecord/lib/active_record/associations/has_one_association.rb index ea769fd48b..68b8b792ad 100644 --- a/activerecord/lib/active_record/associations/has_one_association.rb +++ b/activerecord/lib/active_record/associations/has_one_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Has One Association module Associations class HasOneAssociation < AssociationProxy #:nodoc: def initialize(owner, reflection) diff --git a/activerecord/lib/active_record/associations/has_one_through_association.rb b/activerecord/lib/active_record/associations/has_one_through_association.rb index a79bf943d1..fba0a2bfcc 100644 --- a/activerecord/lib/active_record/associations/has_one_through_association.rb +++ b/activerecord/lib/active_record/associations/has_one_through_association.rb @@ -1,6 +1,7 @@ require "active_record/associations/through_association_scope" module ActiveRecord + # = Active Record Has One Through Association module Associations class HasOneThroughAssociation < HasOneAssociation include ThroughAssociationScope diff --git a/activerecord/lib/active_record/associations/through_association_scope.rb b/activerecord/lib/active_record/associations/through_association_scope.rb index 93bd6e3185..22e1033a9d 100644 --- a/activerecord/lib/active_record/associations/through_association_scope.rb +++ b/activerecord/lib/active_record/associations/through_association_scope.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Through Association Scope module Associations module ThroughAssociationScope diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb index 4a1d6ac758..b273c33e50 100644 --- a/activerecord/lib/active_record/migration.rb +++ b/activerecord/lib/active_record/migration.rb @@ -29,7 +29,7 @@ def initialize(name) end end - # Active Record Migrations + # = Active Record Migrations # # Migrations can manage the evolution of a schema used by several physical # databases. It's a solution to the common problem of adding a field to make diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index 3d8f4a030b..47eef9535e 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -4,11 +4,12 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Named Scopes module NamedScope extend ActiveSupport::Concern module ClassMethods - # Returns an anonymous scope. + # Returns an anonymous \scope. # # posts = Post.scoped # posts.size # Fires "select count(*) from posts" and returns the count @@ -18,10 +19,12 @@ module ClassMethods # fruits = fruits.where(:colour => 'red') if options[:red_only] # fruits = fruits.limit(10) if limited? # - # Anonymous \scopes tend to be useful when procedurally generating complex queries, where passing - # intermediate values (scopes) around as first-class objects is convenient. + # Anonymous \scopes tend to be useful when procedurally generating complex + # queries, where passing intermediate values (scopes) around as first-class + # objects is convenient. # - # You can define a scope that applies to all finders using ActiveRecord::Base.default_scope. + # You can define a scope that applies to all finders using + # ActiveRecord::Base.default_scope. def scoped(options = {}, &block) if options.present? relation = scoped.apply_finder_options(options) diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb index 767ec85432..99f8b431c8 100644 --- a/activerecord/lib/active_record/nested_attributes.rb +++ b/activerecord/lib/active_record/nested_attributes.rb @@ -15,7 +15,7 @@ class TooManyRecords < ActiveRecordError self.nested_attributes_options = {} end - # == Nested Attributes + # = Active Record Nested Attributes # # Nested attributes allow you to save attributes on associated records # through the parent. By default nested attribute updating is turned off, @@ -25,6 +25,7 @@ class TooManyRecords < ActiveRecordError # # The attribute writer is named after the association, which means that # in the following example, two new methods are added to your model: + # # author_attributes=(attributes) and # pages_attributes=(attributes). # diff --git a/activerecord/lib/active_record/observer.rb b/activerecord/lib/active_record/observer.rb index 0ea7fe7365..9554dd8826 100644 --- a/activerecord/lib/active_record/observer.rb +++ b/activerecord/lib/active_record/observer.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/class/attribute' module ActiveRecord + # = Active Record Observer + # # Observer classes respond to lifecycle callbacks to implement trigger-like # behavior outside the original class. This is a great way to reduce the # clutter that normally comes when the model class is burdened with diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb index 10788630a5..9e28aa2a05 100644 --- a/activerecord/lib/active_record/persistence.rb +++ b/activerecord/lib/active_record/persistence.rb @@ -1,6 +1,8 @@ module ActiveRecord + # = Active Record Persistence module Persistence - # Returns true if this object hasn't been saved yet -- that is, a record for the object doesn't exist yet; otherwise, returns false. + # Returns true if this object hasn't been saved yet -- that is, a record + # for the object doesn't exist in the data store yet; otherwise, returns false. def new_record? @new_record end @@ -10,7 +12,8 @@ def destroyed? @destroyed end - # Returns if the record is persisted, i.e. it's not a new record and it was not destroyed. + # Returns if the record is persisted, i.e. it's not a new record and it was + # not destroyed. def persisted? !(new_record? || destroyed?) end @@ -69,8 +72,8 @@ def delete freeze end - # Deletes the record in the database and freezes this instance to reflect that no changes should - # be made (since they can't be persisted). + # Deletes the record in the database and freezes this instance to reflect + # that no changes should be made (since they can't be persisted). def destroy if persisted? self.class.unscoped.where(self.class.arel_table[self.class.primary_key].eq(id)).delete_all @@ -80,10 +83,13 @@ def destroy freeze end - # Returns an instance of the specified +klass+ with the attributes of the current record. This is mostly useful in relation to - # single-table inheritance structures where you want a subclass to appear as the superclass. This can be used along with record - # identification in Action Pack to allow, say, Client < Company to do something like render :partial => @client.becomes(Company) - # to render that instance using the companies/company partial instead of clients/client. + # Returns an instance of the specified +klass+ with the attributes of the + # current record. This is mostly useful in relation to single-table + # inheritance structures where you want a subclass to appear as the + # superclass. This can be used along with record identification in + # Action Pack to allow, say, Client < Company to do something + # like render :partial => @client.becomes(Company) to render that + # instance using the companies/company partial instead of clients/client. # # Note: The new instance will share a link to the same attributes as the original class. So any change to the attributes in either # instance will affect the other. @@ -104,14 +110,15 @@ def update_attribute(name, value) save(:validate => false) end - # Updates all the attributes from the passed-in Hash and saves the record. If the object is invalid, the saving will - # fail and false will be returned. + # Updates all the attributes from the passed-in Hash and saves the record. + # If the object is invalid, the saving will fail and false will be returned. def update_attributes(attributes) self.attributes = attributes save end - # Updates an object just like Base.update_attributes but calls save! instead of save so an exception is raised if the record is invalid. + # Updates an object just like Base.update_attributes but calls save! instead + # of save so an exception is raised if the record is invalid. def update_attributes!(attributes) self.attributes = attributes save! diff --git a/activerecord/lib/active_record/query_cache.rb b/activerecord/lib/active_record/query_cache.rb index 093c6c1e55..d9f85a4e5e 100644 --- a/activerecord/lib/active_record/query_cache.rb +++ b/activerecord/lib/active_record/query_cache.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Query Cache class QueryCache module ClassMethods # Enable the query cache within the block if Active Record is configured. diff --git a/activerecord/lib/active_record/railtie.rb b/activerecord/lib/active_record/railtie.rb index a32fb7d399..37f1ec11a6 100644 --- a/activerecord/lib/active_record/railtie.rb +++ b/activerecord/lib/active_record/railtie.rb @@ -9,6 +9,7 @@ require "action_controller/railtie" module ActiveRecord + # = Active Record Railtie class Railtie < Rails::Railtie config.active_record = ActiveSupport::OrderedOptions.new diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index d4af3d7d15..a82e5d7ed1 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -1,12 +1,16 @@ module ActiveRecord + # = Active Record Reflection module Reflection # :nodoc: extend ActiveSupport::Concern - # Reflection allows you to interrogate Active Record classes and objects about their associations and aggregations. - # This information can, for example, be used in a form builder that took an Active Record object and created input - # fields for all of the attributes depending on their type and displayed the associations to other objects. + # Reflection allows you to interrogate Active Record classes and objects + # about their associations and aggregations. This information can, + # for example, be used in a form builder that took an Active Record object + # and created input fields for all of the attributes depending on their type + # and displayed the associations to other objects. # - # You can find the interface for the AggregateReflection and AssociationReflection classes in the abstract MacroReflection class. + # You can find the interface for the AggregateReflection and AssociationReflection + # classes in the abstract MacroReflection class. module ClassMethods def create_reflection(macro, name, options, active_record) case macro @@ -43,8 +47,11 @@ def reflect_on_aggregation(aggregation) reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil end - # Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a - # certain association type, pass in the symbol (:has_many, :has_one, :belongs_to) for that as the first parameter. + # Returns an array of AssociationReflection objects for all the + # associations in the class. If you only want to reflect on a certain + # association type, pass in the symbol (:has_many, :has_one, + # :belongs_to) for that as the first parameter. + # # Example: # # Account.reflect_on_all_associations # returns an array of all associations @@ -71,8 +78,9 @@ def reflect_on_all_autosave_associations end - # Abstract base class for AggregateReflection and AssociationReflection that describes the interface available for both of - # those classes. Objects of AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods. + # Abstract base class for AggregateReflection and AssociationReflection that + # describes the interface available for both of those classes. Objects of + # AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods. class MacroReflection attr_reader :active_record @@ -80,13 +88,15 @@ def initialize(macro, name, options, active_record) @macro, @name, @options, @active_record = macro, name, options, active_record end - # Returns the name of the macro. For example, composed_of :balance, :class_name => 'Money' will return - # :balance or for has_many :clients it will return :clients. + # Returns the name of the macro. For example, composed_of :balance, + # :class_name => 'Money' will return :balance or for + # has_many :clients it will return :clients. def name @name end - # Returns the macro type. For example, composed_of :balance, :class_name => 'Money' will return :composed_of + # Returns the macro type. For example, + # composed_of :balance, :class_name => 'Money' will return :composed_of # or for has_many :clients will return :has_many. def macro @macro @@ -132,11 +142,13 @@ def derive_class_name end - # Holds all the meta-data about an aggregation as it was specified in the Active Record class. + # Holds all the meta-data about an aggregation as it was specified in the + # Active Record class. class AggregateReflection < MacroReflection #:nodoc: end - # Holds all the meta-data about an association as it was specified in the Active Record class. + # Holds all the meta-data about an association as it was specified in the + # Active Record class. class AssociationReflection < MacroReflection #:nodoc: # Returns the target association's class: # @@ -306,9 +318,12 @@ def derive_primary_key_name end end - # Holds all the meta-data about a :through association as it was specified in the Active Record class. + # Holds all the meta-data about a :through association as it was specified + # in the Active Record class. class ThroughReflection < AssociationReflection #:nodoc: - # Gets the source of the through reflection. It checks both a singularized and pluralized form for :belongs_to or :has_many. + # Gets the source of the through reflection. It checks both a singularized + # and pluralized form for :belongs_to or :has_many. + # # (The :tags association on Tagging below.) # # class Post < ActiveRecord::Base diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb index 5d99a15eda..66970a5ea1 100644 --- a/activerecord/lib/active_record/relation.rb +++ b/activerecord/lib/active_record/relation.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Relation class Relation JoinOperation = Struct.new(:relation, :join_class, :on) ASSOCIATION_METHODS = [:includes, :eager_load, :preload] @@ -75,10 +76,12 @@ def to_a @records end + # Returns size of the records. def size loaded? ? @records.length : count end + # Returns true if there are no records. def empty? loaded? ? @records.empty? : count.zero? end @@ -240,8 +243,9 @@ def destroy(id) # Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')") # Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else']) # - # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent - # associations or call your before_* or +after_destroy+ callbacks, use the +destroy_all+ method instead. + # Both calls delete the affected posts all at once with a single DELETE statement. + # If you need to destroy dependent associations or call your before_* or + # +after_destroy+ callbacks, use the +destroy_all+ method instead. def delete_all(conditions = nil) conditions ? where(conditions).delete_all : arel.delete.tap { reset } end diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb index a833356d15..e2783087ec 100644 --- a/activerecord/lib/active_record/schema.rb +++ b/activerecord/lib/active_record/schema.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Schema + # # Allows programmers to programmatically define a schema in a portable # DSL. This means you can define tables, indexes, etc. without using SQL # directly, so your applications can more easily support multiple diff --git a/activerecord/lib/active_record/schema_dumper.rb b/activerecord/lib/active_record/schema_dumper.rb index 71ef249ee1..a4757773d8 100644 --- a/activerecord/lib/active_record/schema_dumper.rb +++ b/activerecord/lib/active_record/schema_dumper.rb @@ -2,6 +2,8 @@ require 'active_support/core_ext/big_decimal' module ActiveRecord + # = Active Record Schema Dumper + # # This class is used to dump the database schema for some connection to some # output format (i.e., ActiveRecord::Schema). class SchemaDumper #:nodoc: @@ -39,13 +41,14 @@ def header(stream) define_params = @version ? ":version => #{@version}" : "" stream.puts <