Docs and deprecation

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4953 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

4 files changed, 22 insertions, 6 deletions

diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 4f702d65db..41228d30d9 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Added deprecation language for pagination which will become a plugin by Rails 2.0 [DHH]
+
 * Added deprecation language for in_place_editor and auto_complete_field that both pieces will become plugins by Rails 2.0 [DHH]
 
 * Deprecated all of ActionController::Dependencies. All dependency loading is now handled from Active Support [DHH]
diff --git a/actionpack/lib/action_controller/mime_responds.rb b/actionpack/lib/action_controller/mime_responds.rb
index 21905b26c8..07bbbb4732 100644
--- a/actionpack/lib/action_controller/mime_responds.rb
+++ b/actionpack/lib/action_controller/mime_responds.rb
@@ -8,13 +8,13 @@ module ActionController #:nodoc:
       # Without web-service support, an action which collects the data for displaying a list of people
       # might look something like this:
       #
-      #   def list
+      #   def index
       #     @people = Person.find(:all)
       #   end
       # 
       # Here's the same action, with web-service support baked in:
       # 
-      #   def list
+      #   def index
       #     @people = Person.find(:all)
       # 
       #     respond_to do |format|
@@ -30,7 +30,7 @@ module ActionController #:nodoc:
       # Supposing you have an action that adds a new person, optionally creating their company 
       # (by name) if it does not already exist, without web-services, it might look like this:
       # 
-      #   def add
+      #   def create
       #     @company = Company.find_or_create_by_name(params[:company][:name])
       #     @person  = @company.people.create(params[:person])
       # 
@@ -39,7 +39,7 @@ module ActionController #:nodoc:
       # 
       # Here's the same action, with web-service support baked in:
       # 
-      #   def add
+      #   def create
       #     company  = params[:person].delete(:company)
       #     @company = Company.find_or_create_by_name(company[:name])
       #     @person  = @company.people.create(params[:person])
@@ -97,7 +97,6 @@ module ActionController #:nodoc:
       # environment.rb as follows.
       # 
       #   Mime::Type.register "image/jpg", :jpg
-      # 
       def respond_to(*types, &block)
         raise ArgumentError, "respond_to takes either types or a block, never both" unless types.any? ^ block
         block ||= lambda { |responder| types.each { |type| responder.send(type) } }
diff --git a/actionpack/lib/action_controller/mime_type.rb b/actionpack/lib/action_controller/mime_type.rb
index f2b8e32546..165e60cb74 100644
--- a/actionpack/lib/action_controller/mime_type.rb
+++ b/actionpack/lib/action_controller/mime_type.rb
@@ -1,5 +1,18 @@
 module Mime
-  class Type #:nodoc:
+  # Encapsulates the notion of a mime type. Can be used at render time, for example, with:
+  #
+  #   class PostsController < ActionController::Base
+  #     def show
+  #       @post = Post.find(params[:id])
+  #
+  #       respond_to do |format|
+  #         format.html
+  #         format.ics { render :text => post.to_ics, :mime_type => Mime::Type["text/calendar"]  }
+  #         format.xml { render :xml => @people.to_xml }
+  #       end
+  #     end
+  #   end
+  class Type
     # A simple helper class used in parsing the accept header
     class AcceptItem #:nodoc:
       attr_accessor :order, :name, :q
diff --git a/actionpack/lib/action_controller/pagination.rb b/actionpack/lib/action_controller/pagination.rb
index 54084c0361..595a08c7cc 100644
--- a/actionpack/lib/action_controller/pagination.rb
+++ b/actionpack/lib/action_controller/pagination.rb
@@ -1,6 +1,8 @@
 module ActionController
   # === Action Pack pagination for Active Record collections
   #
+  # DEPRECATION WARNING: Pagination will be separated into its own plugin with Rails 2.0.
+  #
   # The Pagination module aids in the process of paging large collections of
   # Active Record objects. It offers macro-style automatic fetching of your
   # model for multiple views, or explicit fetching for single actions. And if