Basic documentation for all the models

1 files changed, 15 insertions, 1 deletions

diff --git a/app/models/active_storage/variation.rb b/app/models/active_storage/variation.rb
index 45274006a2..34b854fd9f 100644
--- a/app/models/active_storage/variation.rb
+++ b/app/models/active_storage/variation.rb
@@ -1,14 +1,25 @@
 require "active_support/core_ext/object/inclusion"
 
-# A set of transformations that can be applied to a blob to create a variant.
+# A set of transformations that can be applied to a blob to create a variant. This class is exposed via 
+# the `ActiveStorage::Blob#variant` method and should rarely be used directly.
+#
+# In case you do need to use this directly, it's instantiated using a hash of transformations where
+# the key is the command and the value is the arguments. Example:
+#
+#   ActiveStorage::Variation.new(resize: "100x100", monochrome: true, trim: true, rotate: "-90")
+#
+# A list of all possible transformations is available at https://www.imagemagick.org/script/mogrify.php.
 class ActiveStorage::Variation
   attr_reader :transformations
 
   class << self
+    # Returns a variation instance with the transformations that were encoded by `#encode`.
     def decode(key)
       new ActiveStorage.verifier.verify(key, purpose: :variation)
     end
 
+    # Returns a signed key for the `transformations`, which can be used to refer to a specific
+    # variation in a URL or combined key (like `ActiveStorage::Variant#key`).
     def encode(transformations)
       ActiveStorage.verifier.generate(transformations, purpose: :variation)
     end
@@ -18,6 +29,8 @@ class ActiveStorage::Variation
     @transformations = transformations
   end
 
+  # Accepts an open MiniMagick image instance, like what's return by `MiniMagick::Image.read(io)`,
+  # and performs the `transformations` against it. The transformed image instance is then returned.
   def transform(image)
     transformations.each do |(method, argument)|
       if eligible_argument?(argument)
@@ -28,6 +41,7 @@ class ActiveStorage::Variation
     end
   end
 
+  # Returns a signed key for all the `transformations` that this variation was instantiated with.
   def key
     self.class.encode(transformations)
   end