- get all comparison operators to document with sphinx - column based, relationship based.

Should fix misunderstandings like [ticket:2177]

3 files changed, 18 insertions, 16 deletions

diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst
index bb3e3ffb5..c23e5f2f7 100644
--- a/doc/build/orm/internals.rst
+++ b/doc/build/orm/internals.rst
@@ -19,10 +19,6 @@ Some key internal constructs are listed here.
     :members:
     :show-inheritance:
 
-.. autoclass:: sqlalchemy.orm.properties.DeferredColumnProperty
-    :members:
-    :show-inheritance:
-
 .. autoclass:: sqlalchemy.orm.state.InstanceState
     :members:
     :show-inheritance:
@@ -39,6 +35,7 @@ Some key internal constructs are listed here.
     :members:
     :show-inheritance:
 
+
 .. autoclass:: sqlalchemy.orm.descriptor_props.SynonymProperty
     :members:
     :show-inheritance:
diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index 96c641f90..259a6ecba 100644
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -545,12 +545,8 @@ should be used in order to acquire the underlying mapped column.  This will
 return a column that is appropriately wrapped in any kind of subquery
 or aliasing that has been applied in the context of the generated SQL statement.
 
-.. autoclass:: sqlalchemy.orm.interfaces.PropComparator
-    :show-inheritance:
-
 .. autofunction:: comparable_property
 
-
 .. _mapper_composite:
 
 Composite Column Types
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index f77225c40..2a646d3e2 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -1061,6 +1061,8 @@ See :ref:`loading_toplevel` for information on
 :func:`~sqlalchemy.orm.subqueryload`. We'll also see another way to "eagerly"
 load in the next section.
 
+.. _ormtutorial_joins:
+
 Querying with Joins
 ====================
 
@@ -1107,6 +1109,11 @@ works better when one of the following forms are used::
     query.join(Address, User.addresses)              # same, with explicit target
     query.join('addresses')                          # same, using a string
 
+As you would expect, the same idea is used for "outer" joins, using the 
+:meth:`~.Query.outerjoin` function::
+
+    query.outerjoin(User.addresses)   # LEFT OUTER JOIN
+
 Note that when :meth:`~sqlalchemy.orm.query.Query.join` is called with an
 explicit target as well as an ON clause, we use a tuple as the argument. This
 is so that multiple joins can be chained together, as in::
@@ -1355,36 +1362,38 @@ usage of EXISTS automatically. Above, the statement can be expressed along the
 Common Relationship Operators
 -----------------------------
 
-Here's all the operators which build on relationships:
+Here's all the operators which build on relationships - each one
+is linked to its API documentation which includes full details on usage
+and behavior:
 
-* equals (used for many-to-one)::
+* :meth:`~.RelationshipProperty.Comparator.__eq__` (many-to-one "equals" comparison)::
 
     query.filter(Address.user == someuser)
 
-* not equals (used for many-to-one)::
+* :meth:`~.RelationshipProperty.Comparator.__ne__` (many-to-one "not equals" comparison)::
 
     query.filter(Address.user != someuser)
 
-* IS NULL (used for many-to-one)::
+* IS NULL (many-to-one comparison, also uses :meth:`~.RelationshipProperty.Comparator.__eq__`)::
 
     query.filter(Address.user == None)
 
-* contains (used for one-to-many and many-to-many collections)::
+* :meth:`~.RelationshipProperty.Comparator.contains` (used for one-to-many collections)::
 
     query.filter(User.addresses.contains(someaddress))
 
-* any (used for one-to-many and many-to-many collections)::
+* :meth:`~.RelationshipProperty.Comparator.any` (used for collections)::
 
     query.filter(User.addresses.any(Address.email_address == 'bar'))
 
     # also takes keyword arguments:
     query.filter(User.addresses.any(email_address='bar'))
 
-* has (used for many-to-one)::
+* :meth:`~.RelationshipProperty.Comparator.has` (used for scalar references)::
 
     query.filter(Address.user.has(name='ed'))
 
-* with_parent (used for any relationship)::
+* :meth:`.Query.with_parent` (used for any relationship)::
 
     session.query(Address).with_parent(someuser, 'addresses')