diff --git a/lib/active_storage/attached.rb b/lib/active_storage/attached.rb
index 6b81545897..8bec129a1a 100644
--- a/lib/active_storage/attached.rb
+++ b/lib/active_storage/attached.rb
@@ -4,6 +4,8 @@ require "active_storage/attachment"
 require "action_dispatch/http/upload"
 require "active_support/core_ext/module/delegation"
 
+# Abstract baseclass for the particular `ActiveStorage::Attached::One` and `ActiveStorage::Attached::Many`
+# classes that both provide proxy access to the blob association for a record.
 class ActiveStorage::Attached
   attr_reader :name, :record
 
diff --git a/lib/active_storage/attached/macros.rb b/lib/active_storage/attached/macros.rb
index 5915793f8a..54c2731c08 100644
--- a/lib/active_storage/attached/macros.rb
+++ b/lib/active_storage/attached/macros.rb
@@ -1,3 +1,4 @@
+# Provides the class-level DSL for declaring that an Active Record model has attached blobs.
 module ActiveStorage::Attached::Macros
   # Specifies the relation between a single attachment and the model.
   #