Some basic documentation for the has_rich_text macro

1 files changed, 18 insertions, 0 deletions

diff --git a/lib/action_text/attribute.rb b/lib/action_text/attribute.rb
index 6ed72fd852..299c26b29f 100644
--- a/lib/action_text/attribute.rb
+++ b/lib/action_text/attribute.rb
@@ -3,6 +3,24 @@ module ActionText
     extend ActiveSupport::Concern
 
     class_methods do
+      # Provides access to a dependent RichText model that holds the body and attachments for a single named rich text attribute.
+      # This dependent attribute is lazily instantiated and will be auto-saved when it's been changed. Example:
+      #
+      #   class Message < ActiveRecord::Base
+      #     has_rich_text :content
+      #   end
+      #
+      #   message = Message.create!(content: "<h1>Funny times!</h1>")
+      #   message.content.to_s # => "<h1>Funny times!</h1>"
+      #   message.content.body.to_plain_text # => "Funny times!"
+      #
+      # The dependent RichText model will also automatically process attachments links as sent via the Trix-powered editor.
+      # These attachments are associated with the RichText model using Active Storage.
+      #
+      # If you wish to preload the dependent RichText model, you can use the named scope:
+      #
+      #   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_emebds # Avoids N+1 queries when you just want the body and attachments.
       def has_rich_text(name)
         class_eval <<-CODE, __FILE__, __LINE__ + 1
           def #{name}