Add doc note for contains_eager() w/ subclasses.

Change-Id: I9634136e1855a081c25b04bb6ae8248f0f94be1c
Fixes: #4130

1 files changed, 13 insertions, 1 deletions

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index e07a6b3d0..86a48f3b9 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -753,7 +753,7 @@ def contains_eager(loadopt, attr, alias=None):
     ``User`` entity, and the returned ``Order`` objects would have the
     ``Order.user`` attribute pre-populated.
 
-    :func:`contains_eager` also accepts an `alias` argument, which is the
+    :func:`.contains_eager` also accepts an `alias` argument, which is the
     string name of an alias, an :func:`~sqlalchemy.sql.expression.alias`
     construct, or an :func:`~sqlalchemy.orm.aliased` construct. Use this when
     the eagerly-loaded rows are to come from an aliased table::
@@ -763,6 +763,18 @@ def contains_eager(loadopt, attr, alias=None):
                 join((user_alias, Order.user)).\
                 options(contains_eager(Order.user, alias=user_alias))
 
+    When using :func:`.contains_eager` in conjunction with inherited
+    subclasses, the :meth:`.RelationshipProperty.of_type` modifier should
+    also be used in order to set up the pathing properly::
+
+        sess.query(Company).\
+            outerjoin(Company.employees.of_type(Manager)).\
+            options(
+                contains_eager(
+                    Company.employees.of_type(Manager),
+                    alias=Manager)
+            )
+
     .. seealso::
 
         :ref:`loading_toplevel`