Update README.md

README.md

@@ -64,6 +64,46 @@ If you'd prefer to use `includes` or `eager_load` rather than `preload`, pass th
   preload_blueprint(use: :includes)
 ```
 
+## Annotations
+
+Some associations may be "hidden" inside methods or field blocks, requiring you to annotate your Blueprints.
+
+```ruby
+# Here is a model with some instance methods
+class Widget < ActiveRecord::Base
+  belongs_to :category
+  belongs_to :project
+  has_many :parts
+
+  # Blueprinter can't see what this method is calling
+  def parts_description
+    # I'm calling the "parts" association, but the caller won't know!
+    parts.map(&:description).join(", ")
+  end
+
+  # Or this one
+  def owner_address
+    project.owner ? project.owner.address.to_s : project.company.address
+  end
+end
+
+# Here's a Blueprint with one association, two annotated fields, and one annotated association
+class WidgetBlueprint < Blueprinter::Base
+  association :category, blueprint: CategoryBlueprint
+
+  # Blueprinter can't see the "parts" association being used here, so we annotate it
+  field :parts_description, preload: :parts
+
+  # Your annotations can be as complex as needed
+  field :owner_address, preload: {project: [:company, {owner: :address}]}
+
+  # You can annotate association blocks, too
+  association :parts, blueprint: PartBlueprint, preload: :draft_parts do |widget|
+    widget.parts + widget.draft_parts
+  end
+end
+```
+
 ## Notes on use
 
 ### Pass the *query* to render, not query *results*
@@ -92,42 +132,15 @@ do_something widgets
 WidgetBlueprint.render(widgets, view: :extended)
 ```
 
-### Annotate hidden associations
+### Use strict_loading to find hidden associations
 
-*blueprinter-activerecord* may feel magical, but it's not magic. Some associations may be "hidden", requiring you to annotate your Blueprints.
+Rails 6.1 added support for `strict_loading`. Depending on your configuration, it will either raise exceptions or log warnings if a query triggers any lazy loading. Very useful for catching "hidden" associations.
 
 ```ruby
-# Here is a method on a model that calls an association
-class Widget < ActiveRecord::Base
-  belongs_to :category
-  has_many :parts
-
-  # Blueprinter can't see what this method is calling
-  def parts_description
-    # I'm calling the "parts" association, but the caller won't know!
-    parts.map(&:description).join(", ")
-  end
-
-  # Or this one
-  def owner_address
-    project.owner ? project.owner.address.to_s : project.company.address
-  end
-end
-
-# Here's a Blueprint with one association and two annotated fields
-class WidgetBlueprint < Blueprinter::Base
-  association :category, blueprint: CategoryBlueprint
-
-  # Blueprinter can't see the "parts" association being used here, so we annotate it
-  field :parts_description, preload: :parts
-
-  # Your annotations can be as complex as needed
-  field :owner_address, preload: {project: [:company, {owner: :address}]}
-end
+widgets = Widget.where(...).strict_loading
+WidgetBlueprint.render(widgets)
 ```
 
-Rails 6.1 added support for `strict_loading`. Depending on your configuration, it will either raise exceptions or log warnings if a query triggers any lazy loading. Very useful for catching any associations Blueprinter can't see.
-
 ## Logging
 
 There are two different logging extensions. You can use them together or separately to measure how much the Preloder extension is, or can, help your application.