Document the rest of lib

3 files changed, 36 insertions, 9 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)
diff --git a/lib/active_storage/attached/many.rb b/lib/active_storage/attached/many.rb
index ea4aade5d7..035cd9c091 100644
--- a/lib/active_storage/attached/many.rb
+++ b/lib/active_storage/attached/many.rb
@@ -1,24 +1,28 @@
-# Representation of multiple attachments to a model.
+# Decorated proxy object representing of multiple attachments to a model.
 class ActiveStorage::Attached::Many < ActiveStorage::Attached
   delegate_missing_to :attachments
 
   # Returns all the associated attachment records.
   #
-  # You don't have to call this method to access the attachments' methods as
-  # they are all available at the model level.
+  # All methods called on this proxy object that aren't listed here will automatically be delegated to `attachments`.
   def attachments
     record.public_send("#{name}_attachments")
   end
 
-  # Associates one or several attachments with the current record, saving
-  # them to the database.
+  # Associates one or several attachments with the current record, saving them to the database.
+  # Examples:
+  #
+  #   document.images.attach(params[:images]) # Array of ActionDispatch::Http::UploadedFile objects
+  #   document.images.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload
+  #   document.images.attach(io: File.open("~/racecar.jpg"), filename: "racecar.jpg", content_type: "image/jpg")
+  #   document.images.attach([ first_blob, second_blob ])
   def attach(*attachables)
     attachables.flatten.collect do |attachable|
       attachments.create!(name: name, blob: create_blob_from(attachable))
     end
   end
 
-  # Checks the presence of attachments.
+  # Returns true if any attachments has been made.
   #
   #   class Gallery < ActiveRecord::Base
   #     has_many_attached :photos
diff --git a/lib/active_storage/attached/one.rb b/lib/active_storage/attached/one.rb
index d255412842..0c522e856e 100644
--- a/lib/active_storage/attached/one.rb
+++ b/lib/active_storage/attached/one.rb
@@ -10,14 +10,19 @@ class ActiveStorage::Attached::One < ActiveStorage::Attached
     record.public_send("#{name}_attachment")
   end
 
-  # Associates a given attachment with the current record, saving it to the
-  # database.
+  # Associates a given attachment with the current record, saving it to the database.
+  # Examples:
+  #
+  #   person.avatar.attach(params[:avatar]) # ActionDispatch::Http::UploadedFile object
+  #   person.avatar.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload
+  #   person.avatar.attach(io: File.open("~/face.jpg"), filename: "face.jpg", content_type: "image/jpg")
+  #   person.avatar.attach(avatar_blob) # ActiveStorage::Blob object
   def attach(attachable)
     write_attachment \
       ActiveStorage::Attachment.create!(record: record, name: name, blob: create_blob_from(attachable))
   end
 
-  # Checks the presence of the attachment.
+  # Returns true if an attachment has been made.
   #
   #   class User < ActiveRecord::Base
   #     has_one_attached :avatar