Update inheritance documentation.

The inheritance documentation is confused, disorganized, and out
of date.  Reorganize and clarify, in particular in preparation
for new inheritance features.

Change-Id: Ibe6a35b4b0432bad866a6afb0598b2cf1b509f10

1 files changed, 4 insertions, 6 deletions

diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 2e61661ed..5bcb28f31 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -694,18 +694,16 @@ def with_polymorphic(base, classes, selectable=False,
     """Produce an :class:`.AliasedClass` construct which specifies
     columns for descendant mappers of the given base.
 
-    .. versionadded:: 0.8
-        :func:`.orm.with_polymorphic` is in addition to the existing
-        :class:`.Query` method :meth:`.Query.with_polymorphic`,
-        which has the same purpose but is not as flexible in its usage.
-
     Using this method will ensure that each descendant mapper's
     tables are included in the FROM clause, and will allow filter()
     criterion to be used against those tables.  The resulting
     instances will also have those columns already loaded so that
     no "post fetch" of those columns will be required.
 
-    See the examples at :ref:`with_polymorphic`.
+    .. seealso::
+
+        :ref:`with_polymorphic` - full discussion of
+        :func:`.orm.with_polymorphic`.
 
     :param base: Base class to be aliased.