Better docs for AV::RecordIdentifier

This commit intends to clarify the scope of ActionView::RecordIdentifier
methods `dom_id` and `dom_class`.

Most of the current documentation comes from da257eb8 (7 years ago) when
the decoupling of ActionView, ActiveRecord and ActiveModel was not a concern.

Since then, steps have been taken to reach such decoupling, especially
8ca17926 which duplicated ActionController::ModelNaming into
ActionView::ModelNaming explaining that:

> These are just a simple helpers for decoupling Active Model, so it does not
> make sense to extract it to Active Support, but the point is to decouple also
> Action View and Action Pack

As of today, ActionView::RecordIdentifier only includes `dom_id` and `dom_class`
so it makes sense to explicitly document those two methods, and leaving the
details of helpers like `div_for` in the corresponding files.

Moreover, I think it's important to mention in the documentation that
ActionView::RecordIdentifier **does not strictly depend on the ActiveRecord API**: any class `Post` implementing `post.to_key` and `post.model_name.param_key` will work.

[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