- add cross-linking for passive_deletes / passive_updates

4 files changed, 25 insertions, 13 deletions

diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index 053369baa..354cfbca4 100644
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -112,7 +112,7 @@ from the database, the ``children`` collection stays empty.
 Using Passive Deletes
 ----------------------
 
-Use ``passive_deletes=True`` to disable child object loading on a DELETE
+Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE
 operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database
 to automatically cascade deletes to child objects::
 
@@ -142,7 +142,7 @@ to automatically cascade deletes to child objects::
     * When using SQLite, foreign key support must be enabled explicitly.
       See :ref:`sqlite_foreign_keys` for details.
 
-When ``passive_deletes`` is applied, the ``children`` relationship will not be
+When :paramref:`~.relationship.passive_deletes` is applied, the ``children`` relationship will not be
 loaded into memory when an instance of ``MyClass`` is marked for deletion. The
 ``cascade="all, delete-orphan"`` *will* take effect for instances of
 ``MyOtherClass`` which are currently present in the session; however for
diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index 1441ef55b..c6a43e28c 100644
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -221,8 +221,8 @@ There are several possibilities here:
   this feature, the database itself can be made to automatically delete rows in the
   "secondary" table as referencing rows in "child" are deleted.   SQLAlchemy
   can be instructed to forego actively loading in the ``Child.parents``
-  collection in this case using the ``passive_deletes=True`` directive
-  on :func:`.relationship`; see :ref:`passive_deletes` for more details
+  collection in this case using the :paramref:`~.relationship.passive_deletes`
+  directive on :func:`.relationship`; see :ref:`passive_deletes` for more details
   on this.
 
 Note again, these behaviors are *only* relevant to the ``secondary`` option
@@ -1563,13 +1563,13 @@ of sync for any moment.
 
 For databases that don't support this, such as SQLite and
 MySQL without their referential integrity options turned
-on, the ``passive_updates`` flag can
+on, the :paramref:`~.relationship.passive_updates` flag can
 be set to ``False``, most preferably on a one-to-many or
 many-to-many :func:`.relationship`, which instructs
 SQLAlchemy to issue UPDATE statements individually for
 objects referenced in the collection, loading them into
 memory if not already locally present. The
-``passive_updates`` flag can also be ``False`` in
+:paramref:`~.relationship.passive_updates` flag can also be ``False`` in
 conjunction with ON UPDATE CASCADE functionality,
 although in that case the unit of work will be issuing
 extra SELECT and UPDATE statements unnecessarily.
@@ -1594,16 +1594,17 @@ A typical mutable primary key setup might look like::
                     ForeignKey('user.username', onupdate="cascade")
                 )
 
-``passive_updates`` is set to ``True`` by default,
+:paramref:`~.relationship.passive_updates` is set to ``True`` by default,
 indicating that ON UPDATE CASCADE is expected to be in
 place in the usual case for foreign keys that expect
 to have a mutating parent key.
 
-``passive_updates=False`` may be configured on any
+A :paramref:`~.relationship.passive_updates` setting of False may be configured on any
 direction of relationship, i.e. one-to-many, many-to-one,
 and many-to-many, although it is much more effective when
 placed just on the one-to-many or many-to-many side.
-Configuring the ``passive_updates=False`` only on the
+Configuring the :paramref:`~.relationship.passive_updates`
+to False only on the
 many-to-one side will have only a partial effect, as the
 unit of work searches only through the current identity
 map for objects that may be referencing the one with a
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 70df9a679..4747c075d 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -315,11 +315,11 @@ class Mapper(_InspectionAttr):
 
            When False, it is assumed that the database does not enforce
            referential integrity and will not be issuing its own CASCADE
-           operation for an update.  The :class:`.Mapper` here will
+           operation for an update.  The unit of work process will
            emit an UPDATE statement for the dependent columns during a
            primary key change.
 
-           ..seealso::
+           .. seealso::
 
                :ref:`passive_updates` - description of a similar feature as
                used with :func:`.relationship`
diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index 879fe7c78..46dd91c6e 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -514,6 +514,11 @@ class RelationshipProperty(StrategizedProperty):
            after a flush occurs so this is a very special use-case
            setting.
 
+           .. seealso::
+
+                :ref:`passive_deletes` - Introductory documentation
+                and examples.
+
         :param passive_updates=True:
           Indicates loading and INSERT/UPDATE/DELETE behavior when the
           source of a foreign key value changes (i.e. an "on update"
@@ -540,10 +545,16 @@ class RelationshipProperty(StrategizedProperty):
           are expected and the database in use doesn't support CASCADE
           (i.e. SQLite, MySQL MyISAM tables).
 
+          .. seealso::
+
+                :ref:`passive_updates` - Introductory documentation and
+                examples.
+
+                :paramref:`.mapper.passive_updates` - a similar flag which
+                takes effect for joined-table inheritance mappings.
+
           Also see the passive_updates flag on ``mapper()``.
 
-          A future SQLAlchemy release will provide a "detect" feature for
-          this flag.
 
         :param post_update:
           this indicates that the relationship should be handled by a