Permalink
Browse files

Merge branch 'master' of github.com:lifo/docrails

Conflicts:
	guides/source/active_record_validations.md
  • Loading branch information...
vijaydev committed Dec 1, 2012
2 parents fb42520 + 9685019 commit 0181c2da977fc3de4e4c4eac602b26ff180cda2c
Showing with 299 additions and 261 deletions.
  1. +13 −3 activerecord/lib/active_record/associations/collection_proxy.rb
  2. +3 −3 activerecord/lib/active_record/relation/calculations.rb
  3. +3 −3 activesupport/lib/active_support/deprecation/instance_delegator.rb
  4. +11 −9 guides/source/action_controller_overview.md
  5. +2 −2 guides/source/action_mailer_basics.md
  6. +6 −6 guides/source/action_view_overview.md
  7. +3 −3 guides/source/active_model_basics.md
  8. +8 −6 guides/source/active_record_basics.md
  9. +11 −9 guides/source/active_record_querying.md
  10. +18 −10 guides/source/active_record_validations.md
  11. +1 −1 guides/source/active_support_core_extensions.md
  12. +17 −15 guides/source/active_support_instrumentation.md
  13. +2 −0 guides/source/api_documentation_guidelines.md
  14. +9 −8 guides/source/asset_pipeline.md
  15. +8 −6 guides/source/association_basics.md
  16. +5 −5 guides/source/caching_with_rails.md
  17. +9 −9 guides/source/command_line.md
  18. +5 −3 guides/source/configuring.md
  19. +8 −6 guides/source/contributing_to_ruby_on_rails.md
  20. +7 −5 guides/source/debugging_rails_applications.md
  21. +2 −0 guides/source/development_dependencies_install.md
  22. +8 −6 guides/source/engines.md
  23. +10 −10 guides/source/form_helpers.md
  24. +9 −9 guides/source/generators.md
  25. +23 −57 guides/source/getting_started.md
  26. +6 −4 guides/source/i18n.md
  27. +3 −1 guides/source/initialization.md
  28. +6 −4 guides/source/layouts_and_rendering.md
  29. +21 −12 guides/source/migrations.md
  30. +2 −2 guides/source/nested_model_forms.md
  31. +3 −1 guides/source/performance_testing.md
  32. +5 −5 guides/source/plugins.md
  33. +3 −3 guides/source/rails_application_templates.md
  34. +7 −5 guides/source/rails_on_rack.md
  35. +8 −6 guides/source/routing.md
  36. +2 −0 guides/source/ruby_on_rails_guides_guidelines.md
  37. +11 −9 guides/source/security.md
  38. +8 −6 guides/source/testing.md
  39. +5 −3 guides/source/upgrading_ruby_on_rails.md
  40. +8 −6 guides/source/working_with_javascript_in_rails.md
@@ -672,7 +672,11 @@ def count(column_name = nil, options = {})
end
# Returns the size of the collection. If the collection hasn't been loaded,
- # it executes a <tt>SELECT COUNT(*)</tt> query.
+ # it executes a <tt>SELECT COUNT(*)</tt> query. Else it calls <tt>collection.size</tt>.
+ #
+ # If the collection has been already loaded +size+ and +length+ are
+ # equivalent. If not and you are going to need the records anyway
+ # +length+ will take one less query. Otherwise +size+ is more efficient.
#
# class Person < ActiveRecord::Base
# has_many :pets
@@ -697,7 +701,8 @@ def size
# Returns the size of the collection calling +size+ on the target.
# If the collection has been already loaded, +length+ and +size+ are
- # equivalent.
+ # equivalent. If not and you are going to need the records anyway this
+ # method will take one less query. Otherwise +size+ is more efficient.
#
# class Person < ActiveRecord::Base
# has_many :pets
@@ -718,7 +723,12 @@ def length
@association.length
end
- # Returns +true+ if the collection is empty.
+ # Returns +true+ if the collection is empty. If the collection has been
+ # loaded or the <tt>:counter_sql</tt> option is provided, it is equivalent
+ # to <tt>collection.size.zero?</tt>. If the collection has not been loaded,
+ # it is equivalent to <tt>collection.exists?</tt>. If the collection has
+ # not already been loaded and you are going to fetch the records anyway it
+ # is better to check <tt>collection.length.zero?</tt>.
#
# class Person < ActiveRecord::Base
# has_many :pets
@@ -111,8 +111,8 @@ def calculate(operation, column_name, options = {})
0
end
- # Use <tt>pluck</tt> as a shortcut to select a single attribute without
- # loading a bunch of records just to grab one attribute you want.
+ # Use <tt>pluck</tt> as a shortcut to select one or more attributes without
+ # loading a bunch of records just to grab the attributes you want.
#
# Person.pluck(:name)
#
@@ -121,7 +121,7 @@ def calculate(operation, column_name, options = {})
# Person.all.map(&:name)
#
# Pluck returns an <tt>Array</tt> of attribute values type-casted to match
- # the plucked column name, if it can be deduced. Plucking an SQL fragment
+ # the plucked column names, if they can be deduced. Plucking an SQL fragment
# returns String values by default.
#
# Examples:
@@ -3,13 +3,13 @@
module ActiveSupport
class Deprecation
- module InstanceDelegator
+ module InstanceDelegator # :nodoc:
def self.included(base)
base.extend(ClassMethods)
base.public_class_method :new
end
- module ClassMethods
+ module ClassMethods # :nodoc:
def include(included_module)
included_module.instance_methods.each { |m| method_added(m) }
super
@@ -21,4 +21,4 @@ def method_added(method_name)
end
end
end
-end
+end
@@ -1,15 +1,17 @@
Action Controller Overview
==========================
-In this guide you will learn how controllers work and how they fit into the request cycle in your application. After reading this guide, you will be able to:
-
-* Follow the flow of a request through a controller
-* Understand why and how to store data in the session or cookies
-* Work with filters to execute code during request processing
-* Use Action Controller's built-in HTTP authentication
-* Stream data directly to the user's browser
-* Filter sensitive parameters so they do not appear in the application's log
-* Deal with exceptions that may be raised during request processing
+In this guide you will learn how controllers work and how they fit into the request cycle in your application.
+
+After reading this guide, you will know:
+
+* Follow the flow of a request through a controller.
+* Understand why and how to store data in the session or cookies.
+* Work with filters to execute code during request processing.
+* Use Action Controller's built-in HTTP authentication.
+* Stream data directly to the user's browser.
+* Filter sensitive parameters so they do not appear in the application's log.
+* Deal with exceptions that may be raised during request processing.
--------------------------------------------------------------------------------
@@ -3,9 +3,9 @@ Action Mailer Basics
This guide should provide you with all you need to get started in sending and receiving emails from and to your application, and many internals of Action Mailer. It also covers how to test your mailers.
---------------------------------------------------------------------------------
+After reading this guide, you will know:
-WARNING. This guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails.
+--------------------------------------------------------------------------------
Introduction
------------
@@ -1,13 +1,13 @@
Action View Overview
====================
-In this guide you will learn:
+After reading this guide, you will know:
-* What Action View is and how to use it with Rails
-* How best to use templates, partials, and layouts
-* What helpers are provided by Action View and how to make your own
-* How to use localized views
-* How to use Action View outside of Rails
+* What Action View is and how to use it with Rails.
+* How best to use templates, partials, and layouts.
+* What helpers are provided by Action View and how to make your own.
+* How to use localized views.
+* How to use Action View outside of Rails.
--------------------------------------------------------------------------------
@@ -1,11 +1,11 @@
Active Model Basics
===================
-This guide should provide you with all you need to get started using model classes. Active Model allows for Action Pack helpers to interact with non-ActiveRecord models. Active Model also helps building custom ORMs for use outside of the Rails framework.
+This guide should provide you with all you need to get started using model classes. Active Model allows for Action Pack helpers to interact with non-Active Record models. Active Model also helps building custom ORMs for use outside of the Rails framework.
---------------------------------------------------------------------------------
+After reading this guide, you will know:
-WARNING. This guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails.
+--------------------------------------------------------------------------------
Introduction
------------
@@ -1,13 +1,15 @@
Active Record Basics
====================
-This guide is an introduction to Active Record. After reading this guide we hope that you'll learn:
+This guide is an introduction to Active Record.
-* What Object Relational Mapping and Active Record are and how they are used in Rails
-* How Active Record fits into the Model-View-Controller paradigm
-* How to use Active Record models to manipulate data stored in a relational database
-* Active Record schema naming conventions
-* The concepts of database migrations, validations and callbacks
+After reading this guide, you will know:
+
+* What Object Relational Mapping and Active Record are and how they are used in Rails.
+* How Active Record fits into the Model-View-Controller paradigm.
+* How to use Active Record models to manipulate data stored in a relational database.
+* Active Record schema naming conventions.
+* The concepts of database migrations, validations and callbacks.
--------------------------------------------------------------------------------
@@ -1,15 +1,17 @@
Active Record Query Interface
=============================
-This guide covers different ways to retrieve data from the database using Active Record. By referring to this guide, you will be able to:
+This guide covers different ways to retrieve data from the database using Active Record.
-* Find records using a variety of methods and conditions
-* Specify the order, retrieved attributes, grouping, and other properties of the found records
-* Use eager loading to reduce the number of database queries needed for data retrieval
-* Use dynamic finders methods
-* Check for the existence of particular records
-* Perform various calculations on Active Record models
-* Run EXPLAIN on relations
+After reading this guide, you will know:
+
+* Find records using a variety of methods and conditions.
+* Specify the order, retrieved attributes, grouping, and other properties of the found records.
+* Use eager loading to reduce the number of database queries needed for data retrieval.
+* Use dynamic finders methods.
+* Check for the existence of particular records.
+* Perform various calculations on Active Record models.
+* Run EXPLAIN on relations.
--------------------------------------------------------------------------------
@@ -466,7 +468,7 @@ The field name can also be a string:
Client.where('locked' => true)
```
-In the case of a belongs_to relationship, an association key can be used to specify the model if an ActiveRecord object is used as the value. This method works with polymorphic relationships as well.
+In the case of a belongs_to relationship, an association key can be used to specify the model if an Active Record object is used as the value. This method works with polymorphic relationships as well.
```ruby
Post.where(author: author)
@@ -4,14 +4,14 @@ Active Record Validations
This guide teaches you how to validate the state of objects before they go into
the database using Active Record's validations feature.
-After reading this guide and trying out the presented concepts, we hope that you'll be able to:
+After reading this guide, you will know:
-* Understand the life cycle of Active Record objects
-* Use the built-in Active Record validation helpers
-* Create your own custom validation methods
-* Work with the error messages generated by the validation process
-* Create callback methods that respond to events in the object life cycle
-* Create special classes that encapsulate common behavior for your callbacks
+* Understand the life cycle of Active Record objects.
+* Use the built-in Active Record validation helpers.
+* Create your own custom validation methods.
+* Work with the error messages generated by the validation process.
+* Create callback methods that respond to events in the object life cycle.
+* Create special classes that encapsulate common behavior for your callbacks.
--------------------------------------------------------------------------------
@@ -365,12 +365,20 @@ class Person < ActiveRecord::Base
end
```
-If you want to be sure that an association is present, you'll need to test whether the foreign key used to map the association is present, and not the associated object itself.
+If you want to be sure that an association is present, you'll need to test the associated object itself, and not whether the foreign key used to map the association is present:
```ruby
class LineItem < ActiveRecord::Base
belongs_to :order
- validates :order_id, presence: true
+ validates :order, presence: true
+end
+```
+
+You should also be sure to have a proper `:inverse_of` as well:
+
+```ruby
+class Order < ActiveRecord::Base
+ has_many :line_items, inverse_of: :order
end
```
@@ -667,7 +675,7 @@ class Invoice < ActiveRecord::Base
:discount_cannot_be_greater_than_total_value
def expiration_date_cannot_be_in_the_past
- if !expiration_date.blank? and expiration_date < Date.today
+ if expiration_date.present? && expiration_date < Date.today
errors.add(:expiration_date, "can't be in the past")
end
end
@@ -5,7 +5,7 @@ Active Support is the Ruby on Rails component responsible for providing Ruby lan
It offers a richer bottom-line at the language level, targeted both at the development of Rails applications, and at the development of Ruby on Rails itself.
-By referring to this guide you will learn the extensions to the Ruby core classes and modules provided by Active Support.
+After reading this guide, you will know:
--------------------------------------------------------------------------------
@@ -3,19 +3,21 @@ Active Support Instrumentation
Active Support is a part of core Rails that provides Ruby language extensions, utilities and other things. One of the things it includes is an instrumentation API that can be used inside an application to measure certain actions that occur within Ruby code, such as that inside a Rails application or the framework itself. It is not limited to Rails, however. It can be used independently in other Ruby scripts if it is so desired.
-In this guide, you will learn how to use the instrumentation API inside of ActiveSupport to measure events inside of Rails and other Ruby code. We cover:
+In this guide, you will learn how to use the instrumentation API inside of Active Support to measure events inside of Rails and other Ruby code.
-* What instrumentation can provide
-* The hooks inside the Rails framework for instrumentation
-* Adding a subscriber to a hook
-* Building a custom instrumentation implementation
+After reading this guide, you will know:
+
+* What instrumentation can provide.
+* The hooks inside the Rails framework for instrumentation.
+* Adding a subscriber to a hook.
+* Building a custom instrumentation implementation.
--------------------------------------------------------------------------------
Introduction to instrumentation
-------------------------------
-The instrumentation API provided by ActiveSupport allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
+The instrumentation API provided by Active Support allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
For example, there is a hook provided within Active Record that is called every time Active Record uses an SQL query on a database. This hook could be **subscribed** to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
@@ -26,8 +28,8 @@ Rails framework hooks
Within the Ruby on Rails framework, there are a number of hooks provided for common events. These are detailed below.
-ActionController
-----------------
+Action Controller
+-----------------
### write_fragment.action_controller
@@ -187,8 +189,8 @@ INFO. Additional keys may be added by the caller.
}
```
-ActionView
-----------
+Action View
+-----------
### render_template.action_view
@@ -216,7 +218,7 @@ ActionView
}
```
-ActiveRecord
+Active Record
------------
### sql.active_record
@@ -246,8 +248,8 @@ INFO. The adapters will add their own data as well.
| `:name` | Record's class |
| `:connection_id` | `self.object_id` |
-ActionMailer
-------------
+Action Mailer
+-------------
### receive.action_mailer
@@ -312,8 +314,8 @@ ActiveResource
| `:request_uri` | Complete URI |
| `:result` | HTTP response object |
-ActiveSupport
--------------
+Active Support
+--------------
### cache_read.active_support
@@ -3,6 +3,8 @@ API Documentation Guidelines
This guide documents the Ruby on Rails API documentation guidelines.
+After reading this guide, you will know:
+
--------------------------------------------------------------------------------
RDoc
@@ -1,14 +1,15 @@
-Asset Pipeline
-==============
+The Asset Pipeline
+==================
This guide covers the asset pipeline introduced in Rails 3.1.
-By referring to this guide you will be able to:
-* Understand what the asset pipeline is and what it does
-* Properly organize your application assets
-* Understand the benefits of the asset pipeline
-* Add a pre-processor to the pipeline
-* Package assets with a gem
+After reading this guide, you will know:
+
+* Understand what the asset pipeline is and what it does.
+* Properly organize your application assets.
+* Understand the benefits of the asset pipeline.
+* Add a pre-processor to the pipeline.
+* Package assets with a gem.
--------------------------------------------------------------------------------
Oops, something went wrong.

0 comments on commit 0181c2d

Please sign in to comment.