doc fixes

* fixed erroneous use of mapped_column() in m2m relationship Table
* Fill in full imports for some relationship examples that had
  partial imports; examples that have no imports, leave empty for now
* converted joined/single inh mappings to annotated style
* We have a problem with @declared_attr in that the error message
  is wrong if the mapped_column() returned doesnt have a type, and/or
  mapped_column() with @declared_attr doesnt use the annotation
* fix thing where sphinx with undoc-members global setting seems to
  no longer tolerate ":attribute:" entries in autodoc classes, which
  is fine we can document the annotations now
* Fix mapper params in inheritance to be on Mapper
* add missing changelog file for instances remove

Change-Id: I9b70b25a320d8122fade68bc4d1f82f8b72b26f3

4 files changed, 100 insertions, 18 deletions

diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py
index 0f66566b0..16062fffa 100644
--- a/lib/sqlalchemy/orm/interfaces.py
+++ b/lib/sqlalchemy/orm/interfaces.py
@@ -335,6 +335,27 @@ class MapperProperty(
 
     """
 
+    info: _InfoType
+    """Info dictionary associated with the object, allowing user-defined
+    data to be associated with this :class:`.InspectionAttr`.
+
+    The dictionary is generated when first accessed.  Alternatively,
+    it can be specified as a constructor argument to the
+    :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite`
+    functions.
+
+    .. versionchanged:: 1.0.0 :attr:`.InspectionAttr.info` moved
+        from :class:`.MapperProperty` so that it can apply to a wider
+        variety of ORM and extension constructs.
+
+    .. seealso::
+
+        :attr:`.QueryableAttribute.info`
+
+        :attr:`.SchemaItem.info`
+
+    """
+
     _has_dataclass_arguments: bool
 
     def _memoized_attr_info(self) -> _InfoType:
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 6a95030b5..61c982029 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -497,14 +497,17 @@ class Mapper(
           SQL expression used to determine the target class for an
           incoming row, when inheriting classes are present.
 
-          This value is commonly a :class:`_schema.Column` object that's
-          present in the mapped :class:`_schema.Table`::
+          May be specified as a string attribute name, or as a SQL
+          expression such as a :class:`_schema.Column` or in a Declarative
+          mapping a :func:`_orm.mapped_column` object.  It is typically
+          expected that the SQL expression corresponds to a column in the
+          base-most mapped :class:`.Table`::
 
             class Employee(Base):
                 __tablename__ = 'employee'
 
-                id = Column(Integer, primary_key=True)
-                discriminator = Column(String(50))
+                id: Mapped[int] = mapped_column(primary_key=True)
+                discriminator: Mapped[str] = mapped_column(String(50))
 
                 __mapper_args__ = {
                     "polymorphic_on":discriminator,
@@ -519,8 +522,8 @@ class Mapper(
             class Employee(Base):
                 __tablename__ = 'employee'
 
-                id = Column(Integer, primary_key=True)
-                discriminator = Column(String(50))
+                id: Mapped[int] = mapped_column(primary_key=True)
+                discriminator: Mapped[str] = mapped_column(String(50))
 
                 __mapper_args__ = {
                     "polymorphic_on":case([
@@ -530,24 +533,18 @@ class Mapper(
                     "polymorphic_identity":"employee"
                 }
 
-          It may also refer to any attribute
-          configured with :func:`.column_property`, or to the
-          string name of one::
+          It may also refer to any attribute using its string name,
+          which is of particular use when using annotated column
+          configurations::
 
                 class Employee(Base):
                     __tablename__ = 'employee'
 
-                    id = Column(Integer, primary_key=True)
-                    discriminator = Column(String(50))
-                    employee_type = column_property(
-                        case([
-                            (discriminator == "EN", "engineer"),
-                            (discriminator == "MA", "manager"),
-                        ], else_="employee")
-                    )
+                    id: Mapped[int] = mapped_column(primary_key=True)
+                    discriminator: Mapped[str]
 
                     __mapper_args__ = {
-                        "polymorphic_on": "employee_type",
+                        "polymorphic_on": "discriminator",
                         "polymorphic_identity": "employee"
                     }
 
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index d11d3af55..6213cfef8 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -358,6 +358,17 @@ class ColumnProperty(
 
         prop: RODescriptorReference[ColumnProperty[_PT]]
 
+        expressions: Sequence[NamedColumn[Any]]
+        """The full sequence of columns referenced by this
+         attribute, adjusted for any aliasing in progress.
+
+        .. versionadded:: 1.3.17
+
+        .. seealso::
+
+           :ref:`maptojoin` - usage example
+        """
+
         def _orm_annotate_column(self, column: _NC) -> _NC:
             """annotate and possibly adapt a column to be returned
             as the mapped-attribute exposed version of the column.
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index ec6f41b28..a518dfc05 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -273,11 +273,59 @@ class ORMExecuteState(util.MemoizedSlots):
     )
 
     session: Session
+    """The :class:`_orm.Session` in use."""
+
     statement: Executable
+    """The SQL statement being invoked.
+
+    For an ORM selection as would
+    be retrieved from :class:`_orm.Query`, this is an instance of
+    :class:`_future.select` that was generated from the ORM query.
+    """
+
     parameters: Optional[_CoreAnyExecuteParams]
+    """Dictionary of parameters that was passed to
+    :meth:`_orm.Session.execute`."""
+
     execution_options: _ExecuteOptions
+    """The complete dictionary of current execution options.
+
+    This is a merge of the statement level options with the
+    locally passed execution options.
+
+    .. seealso::
+
+        :attr:`_orm.ORMExecuteState.local_execution_options`
+
+        :meth:`_sql.Executable.execution_options`
+
+        :ref:`orm_queryguide_execution_options`
+
+    """
+
     local_execution_options: _ExecuteOptions
+    """Dictionary view of the execution options passed to the
+    :meth:`.Session.execute` method.
+
+    This does not include options that may be associated with the statement
+    being invoked.
+
+    .. seealso::
+
+        :attr:`_orm.ORMExecuteState.execution_options`
+
+    """
+
     bind_arguments: _BindArguments
+    """The dictionary passed as the
+    :paramref:`_orm.Session.execute.bind_arguments` dictionary.
+
+    This dictionary may be used by extensions to :class:`_orm.Session` to pass
+    arguments that will assist in determining amongst a set of database
+    connections which one should be used to invoke this statement.
+
+    """
+
     _compile_state_cls: Optional[Type[ORMCompileState]]
     _starting_event_idx: int
     _events_todo: List[Any]
@@ -293,6 +341,11 @@ class ORMExecuteState(util.MemoizedSlots):
         compile_state_cls: Optional[Type[ORMCompileState]],
         events_todo: List[_InstanceLevelDispatch[Session]],
     ):
+        """Construct a new :class:`_orm.ORMExecuteState`.
+
+        this object is constructed internally.
+
+        """
         self.session = session
         self.statement = statement
         self.parameters = parameters