Make :class:`_orm.registry` ``bind`` a private parameter.

Explicitly deprecate ``bind`` from :func:`_orm.declarative_base`
and :func:`_orm.as_declarative`.

Some other documentation cleanup on declarative documentation.

Change-Id: I3f7918d23833b2778ab7009ac5018841deb19f75

5 files changed, 12 insertions, 11 deletions

diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst
index 0ea699180..d058d8b70 100644
--- a/doc/build/orm/basic_relationships.rst
+++ b/doc/build/orm/basic_relationships.rst
@@ -487,7 +487,7 @@ other arguments which depend upon the columns present on an as-yet
 undefined class may also be specified either as Python functions, or more
 commonly as strings.   For most of these
 arguments except that of the main argument, string inputs are
-**evaluated as Python expressions using Python's built-in eval() function.**,
+**evaluated as Python expressions using Python's built-in eval() function**,
 as they are intended to recieve complete SQL expressions.
 
 .. warning:: As the Python ``eval()`` function is used to interpret the
@@ -629,10 +629,10 @@ class were available, we could also apply it afterwards::
 Late-Evaluation for a many-to-many relationship
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many-to-many relationships include a reference to an additional, non-mapped
+Many-to-many relationships include a reference to an additional, typically non-mapped
 :class:`_schema.Table` object that is typically present in the :class:`_schema.MetaData`
 collection referred towards by the :class:`_orm.registry`.   The late-evaluation
-system includes support for having this attribute also be specified as a
+system also includes support for having this attribute be specified as a
 string argument which will be resolved from this :class:`_schema.MetaData`
 collection.  Below we specify an association table ``keyword_author``,
 sharing the :class:`_schema.MetaData` collection associated with our
diff --git a/doc/build/orm/declarative_config.rst b/doc/build/orm/declarative_config.rst
index bf5bd14f6..48c270b4e 100644
--- a/doc/build/orm/declarative_config.rst
+++ b/doc/build/orm/declarative_config.rst
@@ -140,7 +140,8 @@ Things to note above:
   before the other, we can refer to the remote class using its string name.
   This functionality also extends into the area of other arguments specified
   on the :func:`_orm.relationship` such as the "primary join" and "order by"
-  arguments.   See the next section for details on this.
+  arguments.   See the section :ref:`orm_declarative_relationship_eval` for
+  details on this.
 
 
 .. _orm_declarative_mapper_options:
diff --git a/doc/build/orm/declarative_mixins.rst b/doc/build/orm/declarative_mixins.rst
index c5912181d..560bda134 100644
--- a/doc/build/orm/declarative_mixins.rst
+++ b/doc/build/orm/declarative_mixins.rst
@@ -194,7 +194,7 @@ Using Advanced Relationship Arguments (e.g. ``primaryjoin``, etc.)
 :func:`~sqlalchemy.orm.relationship` definitions which require explicit
 primaryjoin, order_by etc. expressions should in all but the most
 simplistic cases use **late bound** forms
-for these arguments, meaning, using either the string form or a lambda.
+for these arguments, meaning, using either the string form or a function/lambda.
 The reason for this is that the related :class:`_schema.Column` objects which are to
 be configured using ``@declared_attr`` are not available to another
 ``@declared_attr`` attribute; while the methods will work and return new
@@ -301,7 +301,7 @@ units such as :func:`.association_proxy`.   The usage of
 be tailored specifically to the target subclass.   An example is when
 constructing multiple :func:`.association_proxy` attributes which each
 target a different type of child object.  Below is an
-:func:`.association_proxy` / mixin example which provides a scalar list of
+:func:`.association_proxy` mixin example which provides a scalar list of
 string values to an implementing class::
 
     from sqlalchemy import Column, Integer, ForeignKey, String
diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst
index a5884ef10..c5c83b171 100644
--- a/doc/build/orm/extensions/declarative/relationships.rst
+++ b/doc/build/orm/extensions/declarative/relationships.rst
@@ -19,5 +19,5 @@ This section is moved to :ref:`orm_declarative_relationship_eval`.
 Configuring Many-to-Many Relationships
 ======================================
 
-this section is moved to :ref:`orm_declarative_relationship_secondary_eval`.
+This section is moved to :ref:`orm_declarative_relationship_secondary_eval`.
 
diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst
index 29045dbb7..5e3c5154a 100644
--- a/doc/build/orm/mapping_styles.rst
+++ b/doc/build/orm/mapping_styles.rst
@@ -350,7 +350,7 @@ that a :meth:`_orm.registry` is present.
 
 In "classical" form, the table metadata is created separately with the
 :class:`_schema.Table` construct, then associated with the ``User`` class via
-the :func:`.mapper` function::
+the :meth:`_orm.registry.map_imperatively` method::
 
     from sqlalchemy import Table, Column, Integer, String, ForeignKey
     from sqlalchemy.orm import registry
@@ -505,7 +505,7 @@ When mapping with the :ref:`imperative <orm_imperative_mapping>` style, the
 class is passed directly as the
 :paramref:`_orm.registry.map_imperatively.class_` argument.
 
-the table, or other from clause object
+The table, or other from clause object
 --------------------------------------
 
 In the vast majority of common cases this is an instance of
@@ -594,8 +594,8 @@ Default Constructor
 The :class:`_orm.registry` applies a default constructor, i.e. ``__init__``
 method, to all mapped classes that don't explicitly have their own
 ``__init__`` method.   The behavior of this method is such that it provides
-a convenient keyword constructor that will accept as keywords the attributes
-that are named.   E.g.::
+a convenient keyword constructor that will accept as optional keyword arguments
+all the attributes that are named.   E.g.::
 
     from sqlalchemy.orm import declarative_base