README.md in grumlin-0.16.1 vs README.md in grumlin-0.17.0

@@ -148,11 +148,11 @@
 shortcuts to make gremlin code more rubyish. Can be used as a drop in replacement for `Grumlin::Sugar`. Remember that
 `Grumlin::Sugar` needs to be included, but `Grumlin::Repository` - extended. **Classes extending `Grumlin::Repository`
 or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts 
 defined in the ancestor.
 
-**Using**:
+**Definition**
 
 ```ruby
 class MyRepository
   extend Grumlin::Repository
 
@@ -165,17 +165,47 @@
     # hasAll(name1: :value, name2: :value) == has(:name1, :value).has(:name2, :value)
     # the `props` shortcut does exactly the same but with `property` steps.
     hasAll(T.label => :triangle, color: color)
   end
 
-  # g and __ are already aware of shortcuts 
-  def red_triangles
+  # g and __ are already aware of shortcuts
+  query(:triangles_with_color, return_mode: :list) do |color| # :list is the default return mode, also possible: :none, :single, :traversal
     g.V.hasLabel(:triangle)
-       .hasColor("red")
-       .toList
+       .hasColor(color)
   end
+  # Note that when using the `query` one does not need to call a termination step like `next` or `toList`,
+  # repository does it automatically in according to the `return_mode` parameter. 
 end
 ```
+
+Each `return_mode` is mapped to a particular termination step:
+- `:list` - `toList`
+- `:single` - `next`
+- `:none` - `iterate`
+- `:traversal` - do not execute the query and return the traversal as is
+
+**Usage**
+
+To execute the query defined in a query block one simply needs to call a method with the same name:
+
+`MyRepository.new.triangles_with_color(:red)`
+
+One can also override the `return_mode`:
+
+`MyRepository.new.triangles_with_color(:red, query_params: { return_mode: :single })`
+
+or even pass a block to the method and a raw traversal will be yielded:
+```ruby
+MyRepository.new.triangles_with_color(:red) do |t|
+  t.has(:other_property, :some_value).toList
+end
+```
+it may be useful for debugging. Note that one needs to call a termination step manually in this case.
+
+`query` also provides a helper for profiling requests:
+`MyRepository.new.triangles_with_color(:red, query_params: { profile: true })`
+
+method will return profiling data of the results.
 
 #### IRB
 
 An example of how to start an IRB session with support for executing gremlin queries: