New docs with YARD (and various cleanups while documenting)

Author: kennethkalmer

.gitignore

@@ -6,3 +6,4 @@ pkg
 *.swp
 .bundle
 tmp/*
+.yardoc

.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--title acts_as_audited
+--exclude lib/generators

Gemfile

@@ -4,3 +4,5 @@ gem "rails", "3.0.1"
 gem "sqlite3-ruby"
 gem "rspec-rails", "2.0.1"
 gem "rcov"
+gem "yard"
+gem "jeweler"

Gemfile.lock

@@ -79,6 +79,7 @@ GEM
     treetop (1.4.8)
       polyglot (>= 0.3.1)
     tzinfo (0.3.23)
+    yard (0.6.1)
 
 PLATFORMS
   ruby
@@ -88,3 +89,4 @@ DEPENDENCIES
   rcov
   rspec-rails (= 2.0.1)
   sqlite3-ruby
+  yard

README.rdoc

@@ -3,13 +3,13 @@
 +acts_as_audited+ is an ActiveRecord extension that logs all changes to your 
 models in an audits table, with optional revision comments. +acts_as_audited+
 has been updated to work with Rails 3, to use it with older version of Rails,
-please see the rails2 branch.
+please see the <tt>rails2</tt> branch.
 
 == Installation
 
 In <tt>Gemfile</tt>:
 
-    gem "acts_as_audited"
+    gem "acts_as_audited", "2.0.0.rc1"
 
 In your application root, run:
 
@@ -29,6 +29,14 @@ Generate the migration:
 
     $ rake db:migrate
 
+== Upgrading
+
+Upgrading to Rails 3, or even between point releases of +acts_as_audited+, might require alterations to the audits table. After every upgrade please run the following generator:
+
+    $ rails g acts_as_audited:upgrade
+
+The upgrade generator will only generate migrations that are missing, or no migrations at all if you are up to date.
+
 == Usage
 
 Declare +acts_as_audited+ on your models:
@@ -59,17 +67,17 @@ If your model declares +attr_accessible+ after +acts_as_audited+, you need to se
 
 == Compatability
 
-+acts_as_audited+ works with Rails 3.0.0 or later.
++acts_as_audited+ works with Rails 3.0.0 or later. For older versions of Rails, please see the <tt>rails2</tt> branch.
 
 == Getting Help
 
-Join the mailing list for getting help or offering suggestions:
-  http://groups.google.com/group/acts_as_audited
+Review the documentation at http://rdoc.info/github/collectiveidea/acts_as_audited
+
+Join the mailing list for getting help or offering suggestions - http://groups.google.com/group/acts_as_audited
 
 == Contributing
 
-Contributions are always welcome. Checkout the latest code on GitHub:
-  http://github.com/collectiveidea/acts_as_audited
+Contributions are always welcome. Checkout the latest code on GitHub - http://github.com/collectiveidea/acts_as_audited
 
 Please include tests with your patches. There are a few gems required to run the tests:
 
@@ -79,5 +87,4 @@ Make sure the tests pass against the version of Rails specified in the Gemfile
 
   $ rake spec test
 
-Please report bugs or feature suggestions on GitHub:
-  http://github.com/collectiveidea/acts_as_audited/issues
+Please report bugs or feature suggestions on GitHub - http://github.com/collectiveidea/acts_as_audited/issues

Rakefile

@@ -1,7 +1,6 @@
 require 'rake'
 require 'rspec/core/rake_task'
 require 'rake/testtask'
-require 'rake/rdoctask'
 
 $:.unshift File.expand_path('../lib', __FILE__)
 
@@ -28,7 +27,7 @@ begin
   end
   # Jeweler::GemcutterTasks.new
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+  puts "Jeweler (or a dependency) not available. Install it with: bundle install"
 end
 
 RSpec::Core::RakeTask.new do |t|
@@ -53,11 +52,10 @@ end
 
 task :test => :check_dependencies
 
-desc 'Generate documentation for the acts_as_audited plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title    = 'acts_as_audited'
-  rdoc.options << '--main' << 'README.rdoc' << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  puts "YARD (or a dependency) not available. Install it with: bundle install"
 end
+

lib/acts_as_audited.rb

@@ -21,12 +21,14 @@
 
 require 'active_record'
 
+# To get started, please review ActsAsAudited::Auditor::ClassMethods#acts_as_audited
 module ActsAsAudited
   VERSION = '2.0.0.rc1'
 
-  # The method to be called to return the current user for logging in the audits. :current_user by default
   mattr_accessor :current_user_method
+  # The method to be called to return the current user for logging in the audits.
   @@current_user_method = :current_user
+
 end
 
 require 'acts_as_audited/auditor'

lib/acts_as_audited/audit.rb

@@ -6,6 +6,7 @@
 # * <tt>user</tt>: the user that performed the change; a string or an ActiveRecord model
 # * <tt>action</tt>: one of create, update, or delete
 # * <tt>audited_changes</tt>: a serialized hash of all the changes
+# * <tt>comment</tt>: a comment set with the audit
 # * <tt>created_at</tt>: Time that the change was performed
 #
 class Audit < ActiveRecord::Base
@@ -19,23 +20,51 @@ class Audit < ActiveRecord::Base
   cattr_accessor :audited_class_names
   self.audited_class_names = Set.new
 
-  def self.audited_classes
-    self.audited_class_names.map(&:constantize)
-  end
+  class << self
+
+    # Returns the list of classes that are being audited
+    def audited_classes
+      audited_class_names.map(&:constantize)
+    end
+
+    # All audits made during the block called will be recorded as made
+    # by +user+. This method is hopefully threadsafe, making it ideal
+    # for background operations that require audit information.
+    def as_user(user, &block)
+      Thread.current[:acts_as_audited_user] = user
+
+      yield
 
-  # All audits made during the block called will be recorded as made
-  # by +user+. This method is hopefully threadsafe, making it ideal
-  # for background operations that require audit information.
-  def self.as_user(user, &block)
-    Thread.current[:acts_as_audited_user] = user
+      Thread.current[:acts_as_audited_user] = nil
+    end
+
+    # @private
+    def reconstruct_attributes(audits)
+      attributes = {}
+      result = audits.collect do |audit|
+        attributes.merge!(audit.new_attributes).merge!(:version => audit.version)
+        yield attributes if block_given?
+      end
+      block_given? ? result : attributes
+    end
 
-    yield
+    # @private
+    def assign_revision_attributes(record, attributes)
+      attributes.each do |attr, val|
+        if record.respond_to?("#{attr}=")
+          record.attributes.has_key?(attr.to_s) ?
+            record[attr] = val :
+            record.send("#{attr}=", val)
+        end
+      end
+      record
+    end
 
-    Thread.current[:acts_as_audited_user] = nil
   end
 
   # Allows user to be set to either a string or an ActiveRecord object
-  def user_as_string=(user) #:nodoc:
+  # @private
+  def user_as_string=(user)
     # reset both either way
     self.user_as_model = self.username = nil
     user.is_a?(ActiveRecord::Base) ?
@@ -45,19 +74,23 @@ def user_as_string=(user) #:nodoc:
   alias_method :user_as_model=, :user=
   alias_method :user=, :user_as_string=
 
-  def user_as_string #:nodoc:
+  # @private
+  def user_as_string
     self.user_as_model || self.username
   end
   alias_method :user_as_model, :user
   alias_method :user, :user_as_string
 
+  # Return an instantance of what the object looked like at this revision. If
+  # the object has been destroyed, this will be a new record.
   def revision
     clazz = auditable_type.constantize
     ( clazz.find_by_id(auditable_id) || clazz.new ).tap do |m|
       Audit.assign_revision_attributes(m, self.class.reconstruct_attributes(ancestors).merge({:version => version}))
     end
   end
 
+  # Return all audits older than the current one.
   def ancestors
     self.class.find(:all, :order => 'version',
       :conditions => ['auditable_id = ? and auditable_type = ? and version <= ?',
@@ -80,26 +113,6 @@ def old_attributes
     end
   end
 
-  def self.reconstruct_attributes(audits)
-    attributes = {}
-    result = audits.collect do |audit|
-      attributes.merge!(audit.new_attributes).merge!(:version => audit.version)
-      yield attributes if block_given?
-    end
-    block_given? ? result : attributes
-  end
-
-  def self.assign_revision_attributes(record, attributes)
-    attributes.each do |attr, val|
-      if record.respond_to?("#{attr}=")
-        record.attributes.has_key?(attr.to_s) ?
-          record[attr] = val :
-          record.send("#{attr}=", val)
-      end
-    end
-    record
-  end
-
 private
 
   def set_version_number

lib/acts_as_audited/audit_sweeper.rb

@@ -1,4 +1,5 @@
-class AuditSweeper < ActionController::Caching::Sweeper #:nodoc:
+# @private
+class AuditSweeper < ActionController::Caching::Sweeper
   observe Audit
 
   def before_create(audit)

lib/acts_as_audited/auditor.rb

@@ -14,7 +14,8 @@ module ActsAsAudited
   module Auditor #:nodoc:
     CALLBACKS = [:audit_create, :audit_update, :audit_destroy]
 
-    def self.included(base) # :nodoc:
+    # @private
+    def self.included(base)
       base.extend ClassMethods
     end
 
@@ -126,11 +127,13 @@ def revision(version)
         revision_with Audit.reconstruct_attributes(audits_to(version))
       end
 
+      # Find the oldest revision recorded prior to the date/time provided.
       def revision_at(date_or_time)
         audits = self.audits.find(:all, :conditions => ["created_at <= ?", date_or_time])
         revision_with Audit.reconstruct_attributes(audits) unless audits.empty?
       end
 
+      # List of attributes that are audited.
       def audited_attributes
         attributes.except(*non_audited_columns)
       end
@@ -235,17 +238,20 @@ def without_auditing(&block)
         block.call.tap { enable_auditing if auditing_was_enabled }
       end
 
+      # Disable auditing.
       def disable_auditing
         write_inheritable_attribute :auditing_enabled, false
       end
 
+      # Enable auditing.
       def enable_auditing
         write_inheritable_attribute :auditing_enabled, true
       end
 
       # All audit operations during the block are recorded as being
       # made by +user+. This is not model specific, the method is a
-      # convenience wrapper around #Audit.as_user.
+      # convenience wrapper around
+      # @see Audit#as_user.
       def audit_as( user, &block )
         Audit.as_user( user, &block )
       end