Add documentation for #17573

Fixes some parts of #23148.

[ci skip]

1 files changed, 8 insertions, 0 deletions

diff --git a/actionpack/lib/action_dispatch/http/cache.rb b/actionpack/lib/action_dispatch/http/cache.rb
index 0f7898a3f8..4bd727c14e 100644
--- a/actionpack/lib/action_dispatch/http/cache.rb
+++ b/actionpack/lib/action_dispatch/http/cache.rb
@@ -80,6 +80,14 @@ module ActionDispatch
           set_header DATE, utc_time.httpdate
         end
 
+        # This method allows you to set the ETag for cached content, which
+        # will be returned to the end user.
+        #
+        # By default, Action Dispatch sets all ETags to be weak.
+        # This ensures that if the content changes only semantically,
+        # the whole page doesn't have to be regenerated from scratch
+        # by the web server. With strong ETags, pages are compared
+        # byte by byte, and are regenerated only if they are not exactly equal.
         def etag=(etag)
           key = ActiveSupport::Cache.expand_cache_key(etag)
           super %(W/"#{Digest::MD5.hexdigest(key)}")