aboutsummaryrefslogtreecommitdiffstats
path: root/activerecord
diff options
context:
space:
mode:
Diffstat (limited to 'activerecord')
-rw-r--r--activerecord/CHANGELOG2
-rwxr-xr-xactiverecord/lib/active_record/fixtures.rb10
-rw-r--r--activerecord/lib/active_record/migration.rb21
-rw-r--r--activerecord/lib/active_record/serializers/json_serializer.rb40
-rw-r--r--activerecord/lib/active_record/serializers/xml_serializer.rb57
-rw-r--r--activerecord/lib/active_record/timestamp.rb2
6 files changed, 84 insertions, 48 deletions
diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG
index 7b218900a7..972aca16e8 100644
--- a/activerecord/CHANGELOG
+++ b/activerecord/CHANGELOG
@@ -1,5 +1,7 @@
*SVN*
+* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria, Sunny Ripert]
+
* Fixed that ActiveRecord#Base.find_or_create/initialize would not honor attr_protected/accessible when used with a hash #11422 [miloops]
* Added ActiveRecord#Base.all/first/last as aliases for find(:all/:first/:last) #11413 [nkallen, thechrisoshow]
diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb
index 0974f8b6bc..8847865451 100755
--- a/activerecord/lib/active_record/fixtures.rb
+++ b/activerecord/lib/active_record/fixtures.rb
@@ -176,11 +176,11 @@ end
# Some times you don't care about the content of the fixtures as much as you care about the volume. In these cases, you can
# mix ERb in with your YAML or CSV fixtures to create a bunch of fixtures for load testing, like:
#
-# <% for i in 1..1000 %>
-# fix_<%= i %>:
-# id: <%= i %>
-# name: guy_<%= 1 %>
-# <% end %>
+# <% for i in 1..1000 %>
+# fix_<%= i %>:
+# id: <%= i %>
+# name: guy_<%= 1 %>
+# <% end %>
#
# This will create 1000 very simple YAML fixtures.
#
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 635eab8428..9945f9cd75 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -91,13 +91,30 @@ module ActiveRecord
#
# The Rails package has several tools to help create and apply migrations.
#
- # To generate a new migration, use <tt>script/generate migration MyNewMigration</tt>
+ # To generate a new migration, you can use
+ # script/generate migration MyNewMigration
+ #
# where MyNewMigration is the name of your migration. The generator will
- # create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
+ # create an empty migration file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
# directory where <tt>nnn</tt> is the next largest migration number.
+ #
# You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
# MyNewMigration.
#
+ # There is a special syntactic shortcut to generate migrations that add fields to a table.
+ # script/generate migration add_fieldname_to_tablename fieldname:string
+ #
+ # This will generate the file <tt>nnn_add_fieldname_to_tablename</tt>, which will look like this:
+ # class AddFieldnameToTablename < ActiveRecord::Migration
+ # def self.up
+ # add_column :tablenames, :fieldname, :string
+ # end
+ #
+ # def self.down
+ # remove_column :tablenames, :fieldname
+ # end
+ # end
+ #
# To run migrations against the currently configured database, use
# <tt>rake db:migrate</tt>. This will update the database by running all of the
# pending migrations, creating the <tt>schema_info</tt> table if missing.
diff --git a/activerecord/lib/active_record/serializers/json_serializer.rb b/activerecord/lib/active_record/serializers/json_serializer.rb
index cf44309de7..c0a5850d5d 100644
--- a/activerecord/lib/active_record/serializers/json_serializer.rb
+++ b/activerecord/lib/active_record/serializers/json_serializer.rb
@@ -8,37 +8,32 @@ module ActiveRecord #:nodoc:
#
# konata = User.find(1)
# konata.to_json
- #
- # {"id": 1, "name": "Konata Izumi", "age": 16,
- # "created_at": "2006/08/01", "awesome": true}
+ # # => {"id": 1, "name": "Konata Izumi", "age": 16,
+ # "created_at": "2006/08/01", "awesome": true}
#
# The :only and :except options can be used to limit the attributes
# included, and work similar to the #attributes method. For example:
#
# konata.to_json(:only => [ :id, :name ])
- #
- # {"id": 1, "name": "Konata Izumi"}
+ # # => {"id": 1, "name": "Konata Izumi"}
#
# konata.to_json(:except => [ :id, :created_at, :age ])
- #
- # {"name": "Konata Izumi", "awesome": true}
+ # # => {"name": "Konata Izumi", "awesome": true}
#
# To include any methods on the model, use :methods.
#
# konata.to_json(:methods => :permalink)
- #
- # {"id": 1, "name": "Konata Izumi", "age": 16,
- # "created_at": "2006/08/01", "awesome": true,
- # "permalink": "1-konata-izumi"}
+ # # => {"id": 1, "name": "Konata Izumi", "age": 16,
+ # "created_at": "2006/08/01", "awesome": true,
+ # "permalink": "1-konata-izumi"}
#
# To include associations, use :include.
#
# konata.to_json(:include => :posts)
- #
- # {"id": 1, "name": "Konata Izumi", "age": 16,
- # "created_at": "2006/08/01", "awesome": true,
- # "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
- # {"id": 2, author_id: 1, "title": "So I was thinking"}]}
+ # # => {"id": 1, "name": "Konata Izumi", "age": 16,
+ # "created_at": "2006/08/01", "awesome": true,
+ # "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
+ # {"id": 2, author_id: 1, "title": "So I was thinking"}]}
#
# 2nd level and higher order associations work as well:
#
@@ -46,13 +41,12 @@ module ActiveRecord #:nodoc:
# :include => { :comments => {
# :only => :body } },
# :only => :title } })
- #
- # {"id": 1, "name": "Konata Izumi", "age": 16,
- # "created_at": "2006/08/01", "awesome": true,
- # "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
- # "title": "Welcome to the weblog"},
- # {"comments": [{"body": "Don't think too hard"}],
- # "title": "So I was thinking"}]}
+ # # => {"id": 1, "name": "Konata Izumi", "age": 16,
+ # "created_at": "2006/08/01", "awesome": true,
+ # "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
+ # "title": "Welcome to the weblog"},
+ # {"comments": [{"body": "Don't think too hard"}],
+ # "title": "So I was thinking"}]}
def to_json(options = {})
JsonSerializer.new(self, options).to_s
end
diff --git a/activerecord/lib/active_record/serializers/xml_serializer.rb b/activerecord/lib/active_record/serializers/xml_serializer.rb
index 84b1a53470..fbd15e06dc 100644
--- a/activerecord/lib/active_record/serializers/xml_serializer.rb
+++ b/activerecord/lib/active_record/serializers/xml_serializer.rb
@@ -1,11 +1,11 @@
module ActiveRecord #:nodoc:
module Serialization
- # Builds an XML document to represent the model. Some configuration is
- # available through +options+, however more complicated cases should
- # override ActiveRecord's to_xml.
+ # Builds an XML document to represent the model. Some configuration is
+ # available through +options+. However more complicated cases should
+ # override ActiveRecord's to_xml method.
#
# By default the generated XML document will include the processing
- # instruction and all object's attributes. For example:
+ # instruction and all the object's attributes. For example:
#
# <?xml version="1.0" encoding="UTF-8"?>
# <topic>
@@ -23,10 +23,10 @@ module ActiveRecord #:nodoc:
# </topic>
#
# This behavior can be controlled with :only, :except,
- # :skip_instruct, :skip_types and :dasherize. The :only and
+ # :skip_instruct, :skip_types and :dasherize. The :only and
# :except options are the same as for the #attributes method.
# The default is to dasherize all column names, to disable this,
- # set :dasherize to false. To not have the column type included
+ # set :dasherize to false. To not have the column type included
# in the XML output, set :skip_types to true.
#
# For instance:
@@ -68,6 +68,36 @@ module ActiveRecord #:nodoc:
# </account>
# </firm>
#
+ # To include deeper levels of associations pass a hash like this:
+ #
+ # firm.to_xml :include => {:account => {}, :clients => {:include => :address}}
+ # <?xml version="1.0" encoding="UTF-8"?>
+ # <firm>
+ # <id type="integer">1</id>
+ # <rating type="integer">1</rating>
+ # <name>37signals</name>
+ # <clients type="array">
+ # <client>
+ # <rating type="integer">1</rating>
+ # <name>Summit</name>
+ # <address>
+ # ...
+ # </address>
+ # </client>
+ # <client>
+ # <rating type="integer">1</rating>
+ # <name>Microsoft</name>
+ # <address>
+ # ...
+ # </address>
+ # </client>
+ # </clients>
+ # <account>
+ # <id type="integer">1</id>
+ # <credit-limit type="integer">50</credit-limit>
+ # </account>
+ # </firm>
+ #
# To include any methods on the object(s) being called use :methods
#
# firm.to_xml :methods => [ :calculated_earnings, :real_earnings ]
@@ -78,7 +108,7 @@ module ActiveRecord #:nodoc:
# <real-earnings>5</real-earnings>
# </firm>
#
- # To call any Proc's on the object(s) use :procs. The Proc's
+ # To call any Procs on the object(s) use :procs. The Procs
# are passed a modified version of the options hash that was
# given to #to_xml.
#
@@ -90,7 +120,7 @@ module ActiveRecord #:nodoc:
# <abc>def</abc>
# </firm>
#
- # Alternatively, you can also just yield the builder object as part of the to_xml call:
+ # Alternatively, you can yield the builder object as part of the to_xml call:
#
# firm.to_xml do |xml|
# xml.creator do
@@ -108,7 +138,7 @@ module ActiveRecord #:nodoc:
# </firm>
#
# You can override the to_xml method in your ActiveRecord::Base
- # subclasses if you need to. The general form of doing this is
+ # subclasses if you need to. The general form of doing this is:
#
# class IHaveMyOwnXML < ActiveRecord::Base
# def to_xml(options = {})
@@ -155,13 +185,6 @@ module ActiveRecord #:nodoc:
!options.has_key?(:dasherize) || options[:dasherize]
end
-
- # To replicate the behavior in ActiveRecord#attributes,
- # :except takes precedence over :only. If :only is not set
- # for a N level model but is set for the N+1 level models,
- # then because :except is set to a default value, the second
- # level model can have both :except and :only set. So if
- # :only is set, always delete :except.
def serializable_attributes
serializable_attribute_names.collect { |name| Attribute.new(name, @record) }
end
@@ -251,7 +274,7 @@ module ActiveRecord #:nodoc:
# There is a significant speed improvement if the value
# does not need to be escaped, as #tag! escapes all values
- # to ensure that valid XML is generated. For known binary
+ # to ensure that valid XML is generated. For known binary
# values, it is at least an order of magnitude faster to
# Base64 encode binary values and directly put them in the
# output XML than to pass the original value or the Base64
diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb
index 84ae3785a2..95e29847cb 100644
--- a/activerecord/lib/active_record/timestamp.rb
+++ b/activerecord/lib/active_record/timestamp.rb
@@ -5,7 +5,7 @@ module ActiveRecord
# Timestamping can be turned off by setting
# <tt>ActiveRecord::Base.record_timestamps = false</tt>
#
- # Timestamps are in the local timezone by default but can use UTC by setting
+ # Timestamps are in the local timezone by default but you can use UTC by setting
# <tt>ActiveRecord::Base.default_timezone = :utc</tt>
module Timestamp
def self.included(base) #:nodoc: