transfer docstrings from @classproperty to props

diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index d0a02381d3e8726753fcaa9434f420c5eb1c71dc..e61c33b5a5264c19b8cdd458a71893cd5587b714 100755 (executable)
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -840,7 +840,11 @@ def _as_declarative(cls, classname, dict_):
                             "be declared as @classproperty callables "
                             "on declarative mixin classes.")
                     elif isinstance(obj, util.classproperty):
-                        dict_[name] = column_copies[obj] = getattr(cls, name)
+                        dict_[name] = ret = \
+                                column_copies[obj] = getattr(cls, name)
+                        if isinstance(ret, (Column, MapperProperty)) and \
+                            ret.doc is None:
+                            ret.doc = obj.__doc__
 
     # apply inherited columns as we should
     for k, v in potential_columns.items():

diff --git a/test/ext/test_declarative.py b/test/ext/test_declarative.py
index 1aafc546914ebf97f6d4d33d5c0b0163a5010e65..5e5c38073500e6894e6adffee7b20db8959b9a93 100644 (file)
--- a/test/ext/test_declarative.py
+++ b/test/ext/test_declarative.py
@@ -2512,6 +2512,39 @@ class DeclarativeMixinPropertyTest(DeclarativeTestBase):
                     filter(MyOtherModel.prop_hoho=='bar').one(),
             m2
         )
+    
+    def test_doc(self):
+        """test documentation transfer.
+        
+        the documentation situation with @classproperty is
+        problematic.   at least see if mapped subclasses
+        get the doc.
+        
+        """
+
+        class MyMixin(object):
+            @classproperty
+            def type_(cls):
+                """this is a document."""
+                return Column(String(50))
+
+            @classproperty
+            def t2(cls):
+                """this is another document."""
+                return column_property(Column(String(50)))
+                
+        class MyModel(Base,MyMixin):
+            __tablename__='test'
+            id =  Column(Integer, primary_key=True)
+        compile_mappers()
+        eq_(
+            MyModel.type_.__doc__,
+            'this is a document.'
+        )
+        eq_(
+            MyModel.t2.__doc__,
+            'this is another document.'
+        )
         
     def test_column_in_mapper_args(self):
         class MyMixin(object):
@@ -2602,6 +2635,8 @@ class DeclarativeMixinPropertyTest(DeclarativeTestBase):
         sess.expire_all()
         eq_(f1.target, t1)
         
+        
+        
     def test_relationship(self):
         self._test_relationship(False)