From ca9413674ea70dc67ab517734af2e40dac21beef Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Wed, 26 Mar 2008 12:27:52 +0000 Subject: Improve documentation. git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activerecord/lib/active_record/fixtures.rb | 10 ++-- activerecord/lib/active_record/migration.rb | 21 +++++++- .../active_record/serializers/json_serializer.rb | 40 +++++++-------- .../active_record/serializers/xml_serializer.rb | 57 +++++++++++++++------- activerecord/lib/active_record/timestamp.rb | 2 +- 5 files changed, 82 insertions(+), 48 deletions(-) (limited to 'activerecord/lib/active_record') 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 script/generate migration MyNewMigration + # 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 nnn_my_new_migration.rb in the db/migrate/ + # create an empty migration file nnn_my_new_migration.rb in the db/migrate/ # directory where nnn is the next largest migration number. + # # You may then edit the self.up and self.down 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 nnn_add_fieldname_to_tablename, 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 # rake db:migrate. This will update the database by running all of the # pending migrations, creating the schema_info 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: # # # @@ -23,10 +23,10 @@ module ActiveRecord #:nodoc: # # # 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: # # # + # To include deeper levels of associations pass a hash like this: + # + # firm.to_xml :include => {:account => {}, :clients => {:include => :address}} + # + # + # 1 + # 1 + # 37signals + # + # + # 1 + # Summit + #
+ # ... + #
+ # + # + # 1 + # Microsoft + #
+ # ... + #
+ # + # + # + # 1 + # 50 + # + # + # # 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: # 5 # # - # 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: # def # # - # 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: # # # 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 # ActiveRecord::Base.record_timestamps = false # - # 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 # ActiveRecord::Base.default_timezone = :utc module Timestamp def self.included(base) #:nodoc: -- cgit v1.2.3