add a note to use column_property with declarative map to a join

diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index 15377436fa04afeb40dd5a5bfa5d400ce1bc66bd..0c8bb0c43daa5dcbf51b6dd09e1f14832f04cc5f 100644 (file)
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -570,6 +570,7 @@ passed in to a mapper as the table.
 
 .. sourcecode:: python+sql
 
+    from sqlalchemy.orm import mapper
     from sqlalchemy.sql import join
     
     class AddressUser(object):
@@ -584,11 +585,31 @@ passed in to a mapper as the table.
         'user_id': [users_table.c.user_id, addresses_table.c.user_id]
     })
 
-A second example:
+Note that the list of columns is equivalent to the usage of :func:`.column_property`
+with multiple columns::
 
-.. sourcecode:: python+sql
+    from sqlalchemy.orm import mapper, column_property
+    
+    mapper(AddressUser, j, properties={
+        'user_id': column_property(users_table.c.user_id, addresses_table.c.user_id)
+    })
 
-    from sqlalchemy.sql import join
+The usage of :func:`.column_property` is required when using declarative to map 
+to multiple columns, since the declarative class parser won't recognize a plain 
+list of columns::
+
+    from sqlalchemy.ext.declarative import declarative_base
+    
+    Base = declarative_base()
+    
+    class AddressUser(Base):
+        __table__ = j
+        
+        user_id = column_property(users_table.c.user_id, addresses_table.c.user_id)
+
+A second example::
+
+        from sqlalchemy.sql import join
 
     # many-to-many join on an association table
     j = join(users_table, userkeywords,
@@ -611,6 +632,7 @@ mappers; these are aggregations of multiple columns into one mapper property,
 which instructs the mapper to keep both of those columns set at the same
 value.
 
+
 Mapping a Class against Arbitrary Selects
 ------------------------------------------