Browse files

Formatting and grammatical fixes for the acts_as_* documentation [sea…

…nhussey, kampers] Closes #9107

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7366 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 5840108 commit 5972fd493b1c5537a1e7ef63e5beca3cf4de8fb9 @NZKoz NZKoz committed Aug 28, 2007
View
16 activerecord/lib/active_record/acts/list.rb
@@ -5,8 +5,8 @@ def self.included(base)
base.extend(ClassMethods)
end
- # This act provides the capabilities for sorting and reordering a number of objects in a list.
- # The class that has this specified needs to have a "position" column defined as an integer on
+ # This +acts_as+ extension provides the capabilities for sorting and reordering a number of objects in a list.
+ # The class that has this specified needs to have a +position+ column defined as an integer on
# the mapped database table.
#
# Todo list example:
@@ -25,9 +25,9 @@ def self.included(base)
module ClassMethods
# Configuration options are:
#
- # * +column+ - specifies the column name to use for keeping the position integer (default: position)
- # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id"
- # (if that hasn't been already) and use that as the foreign key restriction. It's also possible
+ # * +column+ - specifies the column name to use for keeping the position integer (default: +position+)
+ # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach <tt>_id</tt>
+ # (if it hasn't already been added) and use that as the foreign key restriction. It's also possible
# to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
# Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
def acts_as_list(options = {})
@@ -71,7 +71,7 @@ def position_column
# All the methods available to a record that has had <tt>acts_as_list</tt> specified. Each method works
# by assuming the object to be the item in the list, so <tt>chapter.move_lower</tt> would move that chapter
- # lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return true if that chapter is
+ # lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return +true+ if that chapter is
# the first in the list of all chapters.
module InstanceMethods
# Insert the item at the given position (defaults to the top position of 1).
@@ -136,13 +136,13 @@ def decrement_position
update_attribute position_column, self.send(position_column).to_i - 1
end
- # Return true if this object is the first in the list.
+ # Return +true+ if this object is the first in the list.
def first?
return false unless in_list?
self.send(position_column) == 1
end
- # Return true if this object is the last in the list.
+ # Return +true+ if this object is the last in the list.
def last?
return false unless in_list?
self.send(position_column) == bottom_position_in_list
View
26 activerecord/lib/active_record/acts/nested_set.rb
@@ -5,12 +5,12 @@ def self.included(base)
base.extend(ClassMethods)
end
- # This acts provides Nested Set functionality. Nested Set is similiar to Tree, but with
+ # This +acts_as+ extension provides Nested Set functionality. Nested Set is similiar to Tree, but with
# the added feature that you can select the children and all of their descendents with
# a single query. A good use case for this is a threaded post system, where you want
# to display every reply to a comment without multiple selects.
#
- # A google search for "Nested Set" should point you in the direction to explain the
+ # A Google search for "Nested Set" should point you to in the right direction to explain the
# database theory. I figured out a bunch of this from
# http://threebit.net/tutorials/nestedset/tutorial1.html
#
@@ -55,27 +55,27 @@ def self.included(base)
# So, to get all children of an entry, you
# SELECT * WHERE CHILD.LEFT IS BETWEEN PARENT.LEFT AND PARENT.RIGHT
#
- # To get the count, it's (LEFT - RIGHT + 1)/2, etc.
+ # To get the count, it's <tt>(LEFT - RIGHT + 1)/2</tt>, etc.
#
- # To get the direct parent, it falls back to using the PARENT_ID field.
+ # To get the direct parent, it falls back to using the +PARENT_ID+ field.
#
# There are instance methods for all of these.
#
# The structure is good if you need to group things together; the downside is that
# keeping data integrity is a pain, and both adding and removing an entry
# require a full table write.
#
- # This sets up a before_destroy trigger to prune the tree correctly if one of its
+ # This sets up a +before_destroy+ callback to prune the tree correctly if one of its
# elements gets deleted.
#
module ClassMethods
# Configuration options are:
#
- # * +parent_column+ - specifies the column name to use for keeping the position integer (default: parent_id)
- # * +left_column+ - column name for left boundry data, default "lft"
- # * +right_column+ - column name for right boundry data, default "rgt"
- # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id"
- # (if that hasn't been already) and use that as the foreign key restriction. It's also possible
+ # * +parent_column+ - specifies the column name to use for keeping the position integer (default: +parent_id+)
+ # * +left_column+ - column name for left boundry data, default +lft+
+ # * +right_column+ - column name for right boundry data, default +rgt+
+ # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach <tt>_id</tt>
+ # (if it hasn't already been added) and use that as the foreign key restriction. It's also possible
# to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
# Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
def acts_as_nested_set(options = {})
@@ -115,19 +115,19 @@ def parent_column() "#{configuration[:parent_column]}" end
end
module InstanceMethods
- # Returns true is this is a root node.
+ # Returns +true+ is this is a root node.
def root?
parent_id = self[parent_column]
(parent_id == 0 || parent_id.nil?) && (self[left_col_name] == 1) && (self[right_col_name] > self[left_col_name])
end
- # Returns true is this is a child node
+ # Returns +true+ is this is a child node
def child?
parent_id = self[parent_column]
!(parent_id == 0 || parent_id.nil?) && (self[left_col_name] > 1) && (self[right_col_name] > self[left_col_name])
end
- # Returns true if we have no idea what this is
+ # Returns +true+ if we have no idea what this is
def unknown?
!root? && !child?
end
View
18 activerecord/lib/active_record/acts/tree.rb
@@ -5,8 +5,8 @@ def self.included(base)
base.extend(ClassMethods)
end
- # Specify this act if you want to model a tree structure by providing a parent association and a children
- # association. This act requires that you have a foreign key column, which by default is called parent_id.
+ # Specify this +acts_as+ extension if you want to model a tree structure by providing a parent association and a children
+ # association. This requires that you have a foreign key column, which by default is called +parent_id+.
#
# class Category < ActiveRecord::Base
# acts_as_tree :order => "name"
@@ -28,17 +28,17 @@ def self.included(base)
# root.children.first.children.first # => subchild1
#
# In addition to the parent and children associations, the following instance methods are added to the class
- # after specifying the act:
- # * siblings : Returns all the children of the parent, excluding the current node ([ subchild2 ] when called from subchild1)
- # * self_and_siblings : Returns all the children of the parent, including the current node ([ subchild1, subchild2 ] when called from subchild1)
- # * ancestors : Returns all the ancestors of the current node ([child1, root] when called from subchild2)
- # * root : Returns the root of the current node (root when called from subchild2)
+ # after calling <tt>acts_as_tree</tt>:
+ # * <tt>siblings</tt> - Returns all the children of the parent, excluding the current node (<tt>[subchild2]</tt> when called on <tt>subchild1</tt>)
+ # * <tt>self_and_siblings</tt> - Returns all the children of the parent, including the current node (<tt>[subchild1, subchild2]</tt> when called on <tt>subchild1</tt>)
+ # * <tt>ancestors</tt> - Returns all the ancestors of the current node (<tt>[child1, root]</tt> when called on <tt>subchild2</tt>)
+ # * <tt>root</tt> - Returns the root of the current node (<tt>root</tt> when called on <tt>subchild2</tt>)
module ClassMethods
# Configuration options are:
#
- # * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: parent_id)
+ # * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: +parent_id+)
# * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
- # * <tt>counter_cache</tt> - keeps a count in a children_count column if set to true (default: false).
+ # * <tt>counter_cache</tt> - keeps a count in a +children_count+ column if set to +true+ (default: +false+).
def acts_as_tree(options = {})
configuration = { :foreign_key => "parent_id", :order => nil, :counter_cache => nil }
configuration.update(options) if options.is_a?(Hash)

0 comments on commit 5972fd4

Please sign in to comment.