Continued work on docs

.yardopts

@@ -1,2 +1,4 @@
 --files=*.md
 --protected
+--list-undoc
+--exclude lib/friendly_id/migration

README.md

@@ -1,17 +1,8 @@
-<hr>
-**NOTE** This is FriendlyId4 - a rewrite of FriendlyId. For more info about this
-rewrite, and the changes it brings, read [this
-document](https://github.com/norman/friendly_id_4/blob/master/ABOUT.md).
-
-For the current stable FriendlyId, please see:
-
-[https://github.com/norman/friendly_id](https://github.com/norman/friendly_id_4)
-<hr>
 # FriendlyId
 
 FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
-Ruby on Rails. It allows you to create pretty URL's and work with
-human-friendly strings as if they were numeric ids for Active Record models.
+Ruby on Rails. It allows you to create pretty URL's and work with human-friendly
+strings as if they were numeric ids for Active Record models.
 
 Using FriendlyId, it's easy to make your application use URL's like:
 
@@ -24,20 +15,10 @@ instead of:
 ## FriendlyId Features
 
 FriendlyId offers many advanced features, including: slug history and
-versioning, scoped slugs, reserved words, custom slug generators, and
-excellent Unicode support. For complete information on using FriendlyId,
-please see the [FriendlyId Guide](http://norman.github.com/friendly_id/file.Guide.html).
+versioning, scoped slugs, reserved words, and custom slug generators.
 
 FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
-## Docs, Info and Support
-
-* [FriendlyId Guide](http://norman.github.com/friendly_id/file.Guide.html)
-* [API Docs](http://norman.github.com/friendly_id)
-* [Google Group](http://groups.google.com/group/friendly_id)
-* [Source Code](http://github.com/norman/friendly_id/)
-* [Issue Tracker](http://github.com/norman/friendly_id/issues)
-
 ## Rails Quickstart
 
     gem install friendly_id
@@ -70,6 +51,14 @@ FriendlyId is compatible with Active Record **3.0** and **3.1**.
 
     GET http://localhost:3000/users/joe-schmoe
 
+
+### Future Compatibility
+
+FriendlyId will always remain compatible with the current release of Rails, and
+at least one stable release behind. That means that support for 3.0.x will not be
+dropped until a stable release of 3.2 is out, or possibly longer.
+
+
 ## Benchmarks
 
 The latest benchmarks for FriendlyId are maintained

friendly_id.gemspec

@@ -1,11 +1,11 @@
 # encoding: utf-8
 $:.push File.expand_path("../lib", __FILE__)
 
-require "friendly_id/version"
+require "friendly_id"
 
 Gem::Specification.new do |s|
   s.name              = "friendly_id4"
-  s.version           = FriendlyId::Version::STRING
+  s.version           = FriendlyId::VERSION
   s.authors           = ["Norman Clarke"]
   s.email             = ["norman@njclarke.com"]
   s.homepage          = "http://norman.github.com/friendly_id"

lib/friendly_id.rb

@@ -80,6 +80,9 @@ class Post < ActiveRecord::Base
 =end
 module FriendlyId
 
+  # The current version.
+  VERSION = "4.0.0.beta5"
+
   @mutex = Mutex.new
 
   autoload :History,  "friendly_id/history"

lib/friendly_id/history.rb

@@ -1,8 +1,40 @@
 require "friendly_id/slug"
 
 module FriendlyId
+
+=begin
+FriendlyId can maintain a history of your record's older slugs, so if your
+record's friendly_id changes, your URL's won't break.
+
+    class Post < ActiveRecord::Base
+      extend FriendlyId
+      friendly_id :title, :use => :history
+    end
+
+    class PostsController < ApplicationController
+
+      before_filter :find_post
+
+      ...
+      def find_post
+        return unless params[:id]
+        @post = begin
+          Post.find params[:id]
+        rescue ActiveRecord::RecordNotFound
+          Post.find_by_friendly_id params[:id]
+        end
+        # If an old id or a numeric id was used to find the record, then
+        # the request path will not match the post_path, and we should do
+        # a 301 redirect that uses the current friendly_id
+        if request.path != post_path(@post)
+          return redirect_to @post, :status => :moved_permanently
+        end
+      end
+    end
+=end
   module History
 
+    # Configures the model instance to use the History add-on.
     def self.included(klass)
       klass.instance_eval do
         raise "FriendlyId::History is incompatibe with FriendlyId::Scoped" if self < Scoped
@@ -21,7 +53,10 @@ def build_friendly_id_slug
     end
   end
 
+  # Adds a finder that explictly uses slugs from the slug table.
   module Finder
+
+    # Search for a record in the slugs table using the specified slug.
     def find_by_friendly_id(*args)
       with_friendly_id(args.shift).first(*args)
     end

lib/friendly_id/migration.rb

@@ -1,4 +1,5 @@
 class CreateFriendlyIdSlugs < ActiveRecord::Migration
+
   def self.up
     create_table :friendly_id_slugs do |t|
       t.string   :slug,           :null => false

lib/friendly_id/scoped.rb

@@ -78,6 +78,10 @@ class City < ActiveRecord::Base
 
 =end
   module Scoped
+
+
+    # Sets up behavior and configuration options for FriendlyId's scoped slugs
+    # feature.
     def self.included(model_class)
       model_class.instance_eval do
         raise "FriendlyId::Scoped is incompatibe with FriendlyId::History" if self < History
@@ -115,6 +119,9 @@ def scope_column
     # This module overrides {FriendlyId::SlugSequencer#conflict} to consider
     # scope, to avoid adding sequences to slugs under different scopes.
     module SlugSequencer
+
+      private
+
       def conflict
         column = friendly_id_config.scope_column
         conflicts.where("#{column} = ?", sluggable.send(column)).first

lib/friendly_id/slug_sequencer.rb

@@ -8,12 +8,14 @@ def initialize(sluggable)
       @sluggable = sluggable
     end
 
+    # Given a slug, get the next available slug in the sequence.
     def next
       sequence = conflict.slug.split(separator)[1].to_i
       next_sequence = sequence == 0 ? 2 : sequence.next
       "#{normalized}#{separator}#{next_sequence}"
     end
 
+    # Generate a new sequenced slug.
     def generate
       if new_record? or slug_changed?
         conflict? ? self.next : normalized
@@ -22,6 +24,7 @@ def generate
       end
     end
 
+    # Whether or not the model instance's slug has changed.
     def slug_changed?
       separator = Regexp.escape friendly_id_config.sequence_separator
       base != sluggable.current_friendly_id.try(:sub, /#{separator}[\d]*\z/, '')

lib/friendly_id/slugged.rb

@@ -169,10 +169,14 @@ def normalize_friendly_id(value)
       value.to_s.parameterize
     end
 
+    # Gets a new instance of the configured slug sequencing class.
+    #
+    # @see FriendlyId::SlugSequencer
     def slug_sequencer
       friendly_id_config.slug_sequencer_class.new(self)
     end
 
+    # Sets the slug.
     def set_slug
       send "#{friendly_id_config.slug_column}=", slug_sequencer.generate
     end
@@ -208,6 +212,7 @@ def sequence_separator
         @sequence_separator or defaults[:sequence_separator]
       end
 
+      # The column that will be used to store the generated slug.
       def slug_column
         @slug_column or defaults[:slug_column]
       end

lib/generators/friendly_id_generator.rb

@@ -1,11 +1,14 @@
 require 'rails/generators'
 require 'rails/generators/migration'
 
+# This generator adds a migration for the {FriendlyId::History
+# FriendlyId::History} addon.
 class FriendlyIdGenerator < Rails::Generators::Base
   include Rails::Generators::Migration
 
   source_root File.expand_path('../../friendly_id', __FILE__)
 
+  # Copies the migration template to db/migrate.
   def copy_files(*args)
     migration_template 'migration.rb', 'db/migrate/create_friendly_id_slugs.rb'
   end