Merge pull request #18130 from claudiob/better-record-identifier-doc

 Better docs for AV::RecordIdentifier [ci skip]

1 files changed, 42 insertions, 18 deletions

diff --git a/actionview/lib/action_view/record_identifier.rb b/actionview/lib/action_view/record_identifier.rb
index 63f645431a..818a60103f 100644
--- a/actionview/lib/action_view/record_identifier.rb
+++ b/actionview/lib/action_view/record_identifier.rb
@@ -2,29 +2,53 @@ require 'active_support/core_ext/module'
 require 'action_view/model_naming'
 
 module ActionView
-  # The record identifier encapsulates a number of naming conventions for dealing with records, like Active Records or
-  # pretty much any other model type that has an id. These patterns are then used to try elevate the view actions to
-  # a higher logical level.
+  # RecordIdentifier encapsulates methods used by various ActionView helpers
+  # to associate records with DOM elements.
   #
-  #   # routes
-  #   resources :posts
+  # Consider for example the following code that displays the body of a post:
   #
-  #   # view
-  #   <%= div_for(post) do %>    <div id="post_45" class="post">
-  #     <%= post.body %>           What a wonderful world!
-  #   <% end %>                  </div>
+  #   <%= div_for(post) do %>
+  #     <%= post.body %>
+  #   <% end %>
   #
-  #   # controller
-  #   def update
-  #     post = Post.find(params[:id])
-  #     post.update(params[:post])
+  # When +post+ is a new, unsaved ActiveRecord::Base intance, the resulting HTML
+  # is:
   #
-  #     redirect_to(post) # Calls polymorphic_url(post) which in turn calls post_url(post)
-  #   end
+  #    <div id="new_post" class="post">
+  #    </div>
+  #
+  # When +post+ is a persisted ActiveRecord::Base instance, the resulting HTML
+  # is:
+  #
+  #   <div id="post_42" class="post">
+  #     What a wonderful world!
+  #   </div>
+  #
+  # In both cases, the +id+ and +class+ of the wrapping DOM element are
+  # automatically generated, following naming conventions encapsulated by the
+  # RecordIdentifier methods #dom_id and #dom_class:
+  #
+  #   dom_id(Post.new)         # => "new_post"
+  #   dom_class(Post.new)      # => "post"
+  #   dom_id(Post.find 42)     # => "post_42"
+  #   dom_class(Post.find 42)  # => "post"
   #
-  # As the example above shows, you can stop caring to a large extent what the actual id of the post is.
-  # You just know that one is being assigned and that the subsequent calls in redirect_to expect that
-  # same naming convention and allows you to write less code if you follow it.
+  # Note that these methods do not strictly require +Post+ to be a subclass of
+  # ActiveRecord::Base.
+  # Any +Post+ class will do as long as its instances respond to +post.to_key+
+  # and +post.model_name.param_key+; for instance:
+  #
+  #   class Post
+  #     attr_accessor :to_key
+  #
+  #     def model_name
+  #       OpenStruct.new param_key: 'post'
+  #     end
+  #
+  #     def self.find(id)
+  #       new.tap{|post| post.to_key = [id]}
+  #     end
+  #   end
   module RecordIdentifier
     extend self
     extend ModelNaming