Document the rest of lib

1 files changed, 18 insertions, 0 deletions

diff --git a/lib/active_storage/attached/macros.rb b/lib/active_storage/attached/macros.rb
index 11f88f16e5..89297e5bdf 100644
--- a/lib/active_storage/attached/macros.rb
+++ b/lib/active_storage/attached/macros.rb
@@ -9,6 +9,15 @@ module ActiveStorage::Attached::Macros
   # There is no column defined on the model side, Active Storage takes
   # care of the mapping between your records and the attachment.
   #
+  # Under the covers, this relationship is implemented as a `has_one` association to a
+  # `ActiveStorage::Attachment` record and a `has_one-through` association to a
+  # `ActiveStorage::Blob` record. These associations are available as `avatar_attachment`
+  # and `avatar_blob`. But you shouldn't need to work with these associations directly in
+  # most circumstances.
+  #
+  # The system has been designed to having you go through the `ActiveStorage::Attached::One`
+  # proxy that provides the dynamic proxy to the associations and factory methods, like `#attach`.
+  #
   # If the +:dependent+ option isn't set, the attachment will be purged
   # (i.e. destroyed) whenever the record is destroyed.
   def has_one_attached(name, dependent: :purge_later)
@@ -38,6 +47,15 @@ module ActiveStorage::Attached::Macros
   #
   #   Gallery.where(user: Current.user).with_attached_photos
   #
+  # Under the covers, this relationship is implemented as a `has_many` association to a
+  # `ActiveStorage::Attachment` record and a `has_many-through` association to a
+  # `ActiveStorage::Blob` record. These associations are available as `photos_attachments`
+  # and `photos_blobs`. But you shouldn't need to work with these associations directly in
+  # most circumstances.
+  #
+  # The system has been designed to having you go through the `ActiveStorage::Attached::Many`
+  # proxy that provides the dynamic proxy to the associations and factory methods, like `#attach`.
+  #
   # If the +:dependent+ option isn't set, all the attachments will be purged
   # (i.e. destroyed) whenever the record is destroyed.
   def has_many_attached(name, dependent: :purge_later)