Further refine map_column verbiage

The verbiage here continues to be misleading as it implies that
a MapperProperty already exists for the Column when this is not
the case.

Change-Id: Iaa6990dc9693d47d50b15c4815c3c7f6f34d8577
(cherry picked from commit bc9cdd5de0781b93f9cf581f1c5e0d96179ad12e)

1 files changed, 10 insertions, 5 deletions

diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py
index b72c83503..d7e4adcff 100644
--- a/lib/sqlalchemy/orm/descriptor_props.py
+++ b/lib/sqlalchemy/orm/descriptor_props.py
@@ -525,11 +525,16 @@ class SynonymProperty(DescriptorProperty):
 
         :param map_column: **For classical mappings and mappings against
           an existing Table object only**.  if ``True``, the :func:`.synonym`
-          construct will locate the existing named :class:`.MapperProperty`
-          based on the attribute name of this :func:`.synonym`, and assign it
-          to a new attribute linked to the name of this :func:`.synonym`.
-          This is intended to be used with the :paramref:`.synonym.descriptor`
-          parameter::
+          construct will locate the :class:`.Column` object upon the mapped
+          table that would normally be associated with the attribute name of
+          this synonym, and produce a new :class:`.ColumnProperty` that instead
+          maps this :class:`.Column` to the alternate name given as the "name"
+          argument of the synonym; in this way, the usual step of redefining
+          the mapping of the :class:`.Column` to be under a different name is
+          unnecessary. This is usually intended to be used when a
+          :class:`.Column` is to be replaced with an attribute that also uses a
+          descriptor, that is, in conjunction with the
+          :paramref:`.synonym.descriptor` parameter::
 
             my_table = Table(
                 "my_table", metadata,