From 3e06d12ac3de0c1fe946664f23e1941232f5a3b1 Mon Sep 17 00:00:00 2001
From: Sean Kirby <seank@nulogy.com>
Date: Thu, 12 Mar 2020 16:58:49 -0400
Subject: [PATCH] Improve docs for using the AggregateMapper#query method

---
 README.md                      |  7 ++++---
 lib/vorpal/aggregate_mapper.rb | 11 +++++++++++
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e23458f..c6a6dca 100644
--- a/README.md
+++ b/README.md
@@ -203,11 +203,12 @@ It also does not do some things that you might expect from other ORMs:
 
 **A.** Create a method on a [Repository](http://martinfowler.com/eaaCatalog/repository.html)! They have full access to the DB/ORM so you can use [Arel](https://github.com/rails/arel) and go [crazy](http://asciicasts.com/episodes/239-activerecord-relation-walkthrough) or use direct SQL if you want. 
 
-For example:
+For example, use the [#query](https://rubydoc.info/github/nulogy/vorpal/master/Vorpal/AggregateMapper#query-instance_method) method on the [AggregateMapper](https://rubydoc.info/github/nulogy/vorpal/master/Vorpal/AggregateMapper) to access the underyling [ActiveRecordRelation](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html):
 
 ```ruby
-  def find_all
-    @mapper.query.load_all # use the mapper to load all the aggregates
+  def find_special_ones
+    # use `load_all` or `load_one` to convert from ActiveRecord objects to domain POROs.
+    @mapper.query.where(special: true).load_all 
   end
 ```
 
diff --git a/lib/vorpal/aggregate_mapper.rb b/lib/vorpal/aggregate_mapper.rb
index f2f5929..9c2ed27 100644
--- a/lib/vorpal/aggregate_mapper.rb
+++ b/lib/vorpal/aggregate_mapper.rb
@@ -84,6 +84,17 @@ def engine
       @engine
     end
 
+    # Returns a 'Vorpal-aware' [ActiveRecord::Relation](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
+    # for the ActiveRecord object underlying the domain entity mapped by this mapper.
+    #
+    # This method allows you to easily access the power of ActiveRecord::Relation to do more complex
+    # queries in your repositories.
+    #
+    # The ActiveRecord::Relation is 'Vorpal-aware' because it has the {#load_one} and {#load_many} methods
+    # mixed in so that you can get the POROs from your domain model instead of the ActiveRecord
+    # objects normally returned by ActiveRecord::Relation.
+    #
+    # @return [ActiveRecord::Relation]
     def query
       @engine.query(@domain_class)
     end