Merge pull request #42477 from ghiculescu/document-as-eager-loads

Document Active Storage & Action Text eager loading

actiontext/lib/action_text/attribute.rb

@@ -24,6 +24,7 @@ module ActionText
       #
       #   Message.all.with_rich_text_content # Avoids N+1 queries when you just want the body, not the attachments.
       #   Message.all.with_rich_text_content_and_embeds # Avoids N+1 queries when you just want the body and attachments.
+      #   Message.all.with_all_rich_text # Loads all rich text associations.
       #
       #  === Options
       #

activestorage/app/models/active_storage/attachment.rb

@@ -7,6 +7,14 @@ require "active_support/core_ext/module/delegation"
 # on the attachments table prevents blobs from being purged if they’re still attached to any records.
 #
 # Attachments also have access to all methods from {ActiveStorage::Blob}[rdoc-ref:ActiveStorage::Blob].
+#
+# If you wish to preload attachments or blobs, you can use these scopes:
+#
+#   # preloads attachments, their corresponding blobs, and variant records (if using `ActiveStorage.track_variants`)
+#   User.all.with_attached_avatars
+#
+#   # preloads blobs and variant records (if using `ActiveStorage.track_variants`)
+#   User.first.avatars.with_all_variant_records
 class ActiveStorage::Attachment < ActiveStorage::Record
   self.table_name = "active_storage_attachments"
 

activestorage/app/models/active_storage/blob/representable.rb

@@ -12,8 +12,8 @@ module ActiveStorage::Blob::Representable
     has_one_attached :preview_image
   end
 
-  # Returns an ActiveStorage::Variant instance with the set of +transformations+ provided. This is only relevant for image
+  # Returns an ActiveStorage::Variant or ActiveStorage::VariantWithRecord instance with the set of +transformations+ provided.
-  # files, and it allows any image to be transformed for size, colors, and the like. Example:
+  # This is only relevant for image files, and it allows any image to be transformed for size, colors, and the like. Example:
   #
   #   avatar.variant(resize_to_limit: [100, 100]).processed.url
   #

activestorage/app/models/active_storage/variant_with_record.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Like an ActiveStorage::Variant, but keeps detail about the variant in the database as an
+# ActiveStorage::VariantRecord. This is only used if `ActiveStorage.track_variants` is enabled.
 class ActiveStorage::VariantWithRecord
   attr_reader :blob, :variation