restructure dragon to alleviate ambiguity

dragons are eye catching so let's make sure the dragon is
very specific about what it's referring towards

Change-Id: I2faaef2352c7984d4c1c7d599849a9179a1e7776
References: #8732

diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst
index d1d45178d1700ca34fd4edb9137f96e4815df86a..475813f819fee58e983cc1e2dea7fb2c2af9c13e 100644 (file)
--- a/doc/build/orm/declarative_tables.rst
+++ b/doc/build/orm/declarative_tables.rst
@@ -622,11 +622,16 @@ adding a ``FOREIGN KEY`` constraint as well as substituting
       FOREIGN KEY(id) REFERENCES parent (id)
     )
 
-.. note:: The above feature of :func:`_orm.mapped_column` can in theory
-   work for other constructs as well such as :func:`_orm.relationship` and
-   :func:`_orm.composite`.  At the moment, these other use cases are not
-   implemented and raise a ``NotImplementedError``, but may be implemented
-   in future releases.
+.. note:: The feature of :func:`_orm.mapped_column` just described, where
+   a fully constructed set of column arguments may be indicated using
+   :pep:`593` ``Annotated`` objects that contain a "template"
+   :func:`_orm.mapped_column` object to be copied into the attribute, is
+   currently not implemented for other ORM constructs such as
+   :func:`_orm.relationship` and :func:`_orm.composite`.   While this functionality
+   is in theory possible, for the moment attempting to use ``Annotated``
+   to indicate further arguments for :func:`_orm.relationship` and similar
+   will raise a ``NotImplementedError`` exception at runtime, but
+   may be implemented in future releases.
 
 Dataclass features in ``mapped_column()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~