Docs: Dirty, controllers

[ci skip]

CHANGELOG.md

@@ -19,8 +19,9 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/).
 - Removed deprecated `Version#originator`, use `#paper_trail_originator`
 - Using paper_trail.on_destroy(:after) with ActiveRecord's
   belongs_to_required_by_default will produce an error instead of a warning.
-- Removed `warn_about_not_setting_whodunnit` controller method. Please remove
+- Removed the `warn_about_not_setting_whodunnit` controller method. This will
-  callbacks like `skip_after_action :warn_about_not_setting_whodunnit`.
+  only be a problem for you if you are skipping it, eg.
+  `skip_after_action :warn_about_not_setting_whodunnit`, which few people did.
 
 ### Deprecated
 

README.md

@@ -483,6 +483,7 @@ Add a `paper_trail_enabled_for_controller` method to your controller.
 ```ruby
 class ApplicationController < ActionController::Base
   def paper_trail_enabled_for_controller
+    # Don't omit `super` without a good reason.
     super && request.user_agent != 'Disable User-Agent'
   end
 end

lib/paper_trail/frameworks/rails/controller.rb

@@ -20,6 +20,8 @@ module PaperTrail
       #
       # Override this method in your controller to call a different
       # method, e.g. `current_person`, or anything you like.
+      #
+      # @api public
       def user_for_paper_trail
         return unless defined?(current_user)
         ActiveSupport::VERSION::MAJOR >= 4 ? current_user.try!(:id) : current_user.try(:id)
@@ -45,6 +47,8 @@ module PaperTrail
       # Use the `:meta` option to
       # `PaperTrail::Model::ClassMethods.has_paper_trail` to store any extra
       # model-level data you need.
+      #
+      # @api public
       def info_for_paper_trail
         {}
       end
@@ -54,6 +58,15 @@ module PaperTrail
       #
       # Override this method in your controller to specify when PaperTrail
       # should be off.
+      #
+      # ```
+      # def paper_trail_enabled_for_controller
+      #   # Don't omit `super` without a good reason.
+      #   super && request.user_agent != 'Disable User-Agent'
+      # end
+      # ```
+      #
+      # @api public
       def paper_trail_enabled_for_controller
         ::PaperTrail.enabled?
       end
@@ -62,11 +75,15 @@ module PaperTrail
 
       # Tells PaperTrail whether versions should be saved in the current
       # request.
+      #
+      # @api public
       def set_paper_trail_enabled_for_controller
         ::PaperTrail.request.enabled_for_controller = paper_trail_enabled_for_controller
       end
 
       # Tells PaperTrail who is responsible for any changes that occur.
+      #
+      # @api public
       def set_paper_trail_whodunnit
         if ::PaperTrail.request.enabled_for_controller?
           ::PaperTrail.request.whodunnit = user_for_paper_trail
@@ -75,6 +92,8 @@ module PaperTrail
 
       # Tells PaperTrail any information from the controller you want to store
       # alongside any changes that occur.
+      #
+      # @api public
       def set_paper_trail_controller_info
         if ::PaperTrail.request.enabled_for_controller?
           ::PaperTrail.request.controller_info = info_for_paper_trail

lib/paper_trail/model_config.rb

@@ -63,6 +63,8 @@ module PaperTrail
     end
 
     # Adds a callback that records a version after a "create" event.
+    #
+    # @api public
     def on_create
       @model_class.after_create { |r|
         r.paper_trail.record_create if r.paper_trail.save_version?
@@ -72,6 +74,8 @@ module PaperTrail
     end
 
     # Adds a callback that records a version before or after a "destroy" event.
+    #
+    # @api public
     def on_destroy(recording_order = "before")
       unless %w[after before].include?(recording_order.to_s)
         raise ArgumentError, 'recording order can only be "after" or "before"'
@@ -91,6 +95,8 @@ module PaperTrail
     end
 
     # Adds a callback that records a version after an "update" event.
+    #
+    # @api public
     def on_update
       @model_class.before_save { |r|
         r.paper_trail.reset_timestamp_attrs_for_update_if_needed

lib/paper_trail/record_trail.rb

@@ -27,6 +27,7 @@ module PaperTrail
     # > instead, similar to the other branch in reify_has_one.
     # > -Sean Griffin (https://github.com/airblade/paper_trail/pull/899)
     #
+    # @api private
     def appear_as_new_record
       @record.instance_eval {
         alias :old_new_record? :new_record?
@@ -137,6 +138,8 @@ module PaperTrail
     end
 
     # Updates `data` from the model's `meta` option and from `controller_info`.
+    # Metadata is always recorded; that means all three events (create, update,
+    # destroy) and `update_columns`.
     # @api private
     def merge_metadata_into(data)
       merge_metadata_from_model_into(data)
@@ -204,6 +207,8 @@ module PaperTrail
 
     # Returns hash of attributes (with appropriate attributes serialized),
     # omitting attributes to be skipped.
+    #
+    # @api private
     def object_attrs_for_paper_trail
       attrs = attributes_before_change.except(*@record.paper_trail_options[:skip])
       AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs)
@@ -211,11 +216,15 @@ module PaperTrail
     end
 
     # Returns who put `@record` into its current state.
+    #
+    # @api public
     def originator
       (source_version || versions.last).try(:whodunnit)
     end
 
     # Returns the object (not a Version) as it was most recently.
+    #
+    # @api public
     def previous_version
       (source_version ? source_version.previous : versions.last).try(:reify)
     end
@@ -300,7 +309,9 @@ module PaperTrail
       @in_after_callback = false
     end
 
-    # Returns data for record_update
+    # Used during `record_update`, returns a hash of data suitable for an AR
+    # `create`. That is, all the attributes of the nascent `Version` record.
+    #
     # @api private
     def data_for_update
       data = {
@@ -351,6 +362,7 @@ module PaperTrail
     # column, then a hash can be used in the assignment, otherwise the column
     # is a `text` column, and we must perform the serialization here, using
     # `PaperTrail.serializer`.
+    #
     # @api private
     def recordable_object
       if @record.class.paper_trail.version_class.object_col_is_json?
@@ -365,6 +377,7 @@ module PaperTrail
     # a postgres `json` column, then a hash can be used in the assignment,
     # otherwise the column is a `text` column, and we must perform the
     # serialization here, using `PaperTrail.serializer`.
+    #
     # @api private
     def recordable_object_changes(changes)
       if @record.class.paper_trail.version_class.object_changes_col_is_json?
@@ -432,6 +445,9 @@ module PaperTrail
     # creates a version. A version is created regardless of options such as
     # `:on`, `:if`, or `:unless`.
     #
+    # This is an "update" event. That is, we record the same data we would in
+    # the case of a normal AR `update`.
+    #
     # TODO: look into leveraging the `after_touch` callback from
     # `ActiveRecord` to allow the regular `touch` method to generate a version
     # as normal. May make sense to switch the `record_update` method to
@@ -520,6 +536,9 @@ module PaperTrail
       data[:transaction_id] = PaperTrail.request.transaction_id
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def attribute_changed_in_latest_version?(attr_name)
       if @in_after_callback && RAILS_GTE_5_1
@@ -529,6 +548,8 @@ module PaperTrail
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
     # @api private
     def attribute_in_previous_version(attr_name)
       if @in_after_callback && RAILS_GTE_5_1
@@ -538,6 +559,9 @@ module PaperTrail
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def changed_in_latest_version
       if @in_after_callback && RAILS_GTE_5_1
@@ -547,6 +571,9 @@ module PaperTrail
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def changes_in_latest_version
       if @in_after_callback && RAILS_GTE_5_1
@@ -557,6 +584,7 @@ module PaperTrail
     end
 
     # Given a HABTM association, returns an array of ids.
+    #
     # @api private
     def habtm_assoc_ids(habtm_assoc)
       current = @record.send(habtm_assoc.name).to_a.map(&:id) # TODO: `pluck` would use less memory