Readme updates.

README.rdoc

@@ -1,11 +1,123 @@
 == Devise
 
-Flexible authentication solution for Rails with Warden.
+Devise is a flexible authentication solution for Rails based on Warden. It:
+
+* Is Rack based;
+* Is a complete MVC solution based on Rails engines;
+* Allows you to have multiple roles (or models/scopes) signed in at the same time;
+* Is based on a modularity concept: use just what you really need.
+
+Right now it's composed of four mainly modules:
+
+* Authenticable: responsible for encrypting password and validating authenticity of a user while signing in.
+* Confirmable: responsible for verifying whether an account is already confirmed to sign in, and to send emails with confirmation instructions.
+* Recoverable: takes care of reseting the user password and send reset instructions.
+* Validatable: creates all needed validations for a user email and password. It's totally optional, so you're able to to create the validations by yourself.
 
 == Dependencies
 
-http://github.com/hassox/warden
+Devise is based on "Warden":http://github.com/hassox/warden, a Rack Authentication Framework from "hassox":http://github.com/hassox, so you're gonna need to install this gem. Current warden version is 0.4.0. Please ensure you have it installed in order to user devise (see instalation below).
 
-== License
+== Installation
 
-MIT License. Copyright 2009 Plataforma Tecnologia.
+Install warden gem if you don't have it installed:
+
+  sudo gem install warden
+
+Install devise as an engine (plugin) inside your app:
+
+  script/plugin install git://github.com/plataformatec/devise.git
+
+And you're ready.
+
+== Basic Usage
+
+Devise must be setted up within the model (or models) you want to use, and devise routes must be created inside your routes.rb file. Let's start by the model, assuming you already have a User model, just do this to have your authentication working:
+
+  class User < ActiveRecord::Base
+    devise
+  end
+
+This line adds devise authenticable automatically for you inside your User class. You could also include the other modules as below:
+
+  # Same as using only devise, authenticable is activated by default
+  devise :authenticable
+  # Include confirmable
+  devise :confirmable
+  # Include recoverable
+  devise :recoverable
+  # Include validatable
+  devise :validatable
+  # Include all of them
+  devise :confirmable, :recoverable, :validatable
+  # Same as above, include all of them
+  devise :all
+
+Note that validations aren't added by default, so you're able to customize it. In order to have automatic validations working just include :validatable.
+
+The next step after setting up your model is to configure your routes for devise. You do this by opening up your config/routes.rb and adding:
+
+  map.devise_for :users
+
+This is going to look inside you User model and create the needed routes:
+
+# Session routes for Authenticable (default)
+     new_user_session GET    /users/session/new(.:format)      {:controller=>"sessions", :action=>"new"}
+         user_session DELETE /users/session(.:format)          {:controller=>"sessions", :action=>"destroy"}
+                      POST   /users/session(.:format)          {:controller=>"sessions", :action=>"create"}
+
+# Password routes for Recoverable, if User model has :recoverable configured
+    new_user_password GET    /user/password/new(.:format)     {:controller=>"passwords", :action=>"new"}
+   edit_user_password GET    /user/password/edit(.:format)    {:controller=>"passwords", :action=>"edit"}
+        user_password PUT    /user/password(.:format)         {:controller=>"passwords", :action=>"update"}
+                      POST   /user/password(.:format)         {:controller=>"passwords", :action=>"create"}
+
+# Confirmation routes for Confirmable, if User model has :confirmable configured
+new_user_confirmation GET    /user/confirmation/new(.:format) {:controller=>"confirmations", :action=>"new"}
+    user_confirmation GET    /user/confirmation(.:format)     {:controller=>"confirmations", :action=>"show"}
+                      POST   /user/confirmation(.:format)     {:controller=>"confirmations", :action=>"create"}
+
+You can run the routes rake task to verify what routes are being created by devise.
+There are also some options available for configuring your routes:
+
+* :as => Let's you setup the path name that will be used, as rails routes does. The following route configuration would setup your route as /accounts/session and so on:
+
+  map.devise_for :users, :as => 'accounts'
+
+* :class_name => setup a different class to be looked up by devise, if it cannot be correctly find by the route name.
+
+  map.devise_for :users, :class_name => 'Account'
+
+And that is it! Devise is gonna create some helpers to use inside your controllers and views. To setup a controller that needs user authentication, just add this before_filter:
+
+  before_filter :sign_in_user!
+
+To verify if a user is signed in, you have the following helper:
+
+  user_signed_in?
+
+And to get the current signed in user this helper is available:
+
+  current_user
+
+Devise let's you setup as many roles as you want, so let's say you already have this User model and also want an Admin model with the same authentication stuff, but not confirmation or password recovery. Just follow the same steps:
+
+  # Inside your Admin model
+  devise :validatable
+  # Inside your routes
+  map.devise_for :admin
+  # Inside your protected controller
+  before_filter :sign_in_admin!
+  # Inside your controllers and views
+  admin_signed_in?
+  current_admin
+
+== TODO
+
+Please refer to TODO file.
+
+== Bugs and Feedback
+
+If you discover any bugs or want to drop a line, feel free to create an issue.
+
+MIT License. Copyright 2009 Plataforma Tecnologia. http://blog.plataformatec.com.br

lib/devise/models/confirmable.rb

@@ -4,7 +4,7 @@ module Devise
   module Models
 
     # Confirmable is responsible to verify if an account is already confirmed to
-    # sign in, and to send emails with confirmation instructions
+    # sign in, and to send emails with confirmation instructions.
     # Confirmation instructions are sent to the user email after creating a
     # record, after updating it's email and also when manually requested by
     # a new confirmation instruction request.