Docs: signatures for methods returning relations

README.md

@@ -19,16 +19,14 @@ This gem adds a few Rake tasks to generate Ruby Interface (RBI) files for dynami
 
 ```
 # -- Gemfile --
-
+# In the default group (same as sorbet-runtime) because of "Features Provided at Runtime" below
 gem 'sorbet-rails'
 ```
 
 ```sh
 ❯ bundle install
 ```
 
-Warning: *don't* add `sorbet-rails` to a specific environment group (eg. `development` only). `sorbet-rails` adds a bunch of helper methods to your Rails runtime as well as generators for RBI files. You'll want to run the gem in all environments.
-
 3. Generate RBI files for your routes, models, etc
 ```sh
 ❯ rake rails_rbi:routes
@@ -148,6 +146,22 @@ Since mailing action methods is based on instance methods defined in a mailer cl
 - If not, all the params in the mailing action method will be T.untyped.
 - For return type though, the mailing action method will return `ActionMailer::MessageDelivery` instead of the return type of the instance method.
 
+## Features Provided at Runtime
+
+In addition to features provided by the static generator, `sorbet-rails` can
+provide additional features when `require`d. This is why the installation
+instructions specify that `sorbet-rails` should be placed in the default group
+of the `Gemfile`, not a specific environment group (eg. `development` only).
+
+- Relation class: Making the relations available at runtime (they are normally private constants, the gem makes them public)
+  - Examples: `User::ActiveRecord_Relation`, `User::ActiveRecord_AssociationRelation`
+- Model: `find_n`, `first_n`, `last_n` are the methods we added. `pluck_to_tstruct` as well.
+- Controller: adding `fetch_typed` and `require_typed`
+
+Discussion:
+[#211](https://github.com/chanzuckerberg/sorbet-rails/issues/211),
+[#214](https://github.com/chanzuckerberg/sorbet-rails/pull/214#issuecomment-546505485)
+
 ## Tips & Tricks
 
 ### Overriding generated signatures
@@ -260,6 +274,20 @@ Wizard.all.pluck_to_tstruct(TA[WizardStruct].new)  # T::Array[WizardStruct]
 
 This method is based on [pluck_to_hash](https://github.com/girishso/pluck_to_hash) gem.
 
+### How to write signatures for methods returning relations
+
+```ruby
+# app/queries/bacon_query.rb
+class BaconQuery
+  sig { returns(ActiveRecord::Relation) }
+  def chunky
+    Bacon.where(chunky: true)
+  end
+end
+```
+
+It is not currently possible to use `returns(Bacon::ActiveRecord_Relation)`. It will raise a `NameError: uninitialized constant Bacon::ActiveRecord_Relation`.
+
 ## Extending Model Generation Task with Custom Plugins
 
 `sorbet-rails` support a customizable plugin system that you can use to generate additional RBI for each model. This will be useful to generate RBI for methods dynamically added by gems or private concerns. If you write plugins for public gems, please feel free to contribute it to this repo.