FIX deprecated properties correctly wraps the property's docstring (scikit-learn#20385)

thomasjpfan · samronsin · commit cad1277cd47e · 2021-11-30T17:23:11.000+01:00
diff --git a/doc/whats_new/v1.0.rst b/doc/whats_new/v1.0.rst
@@ -604,6 +604,9 @@ Changelog
   precision of the computed variance was very poor when the real variance is
   exactly zero. :pr:`19766` by :user:`Jérémie du Boisberranger <jeremiedbb>`.
 
+- |Fix| Propreties that are decorated with :func:`utils.deprecated` correctly
+  wraps the property's docstring. :pr:`20385` by `Thomas Fan`_.
+
 :mod:`sklearn.validation`
 .........................
 
diff --git a/sklearn/utils/deprecation.py b/sklearn/utils/deprecation.py
@@ -98,10 +98,13 @@ def _decorate_property(self, prop):
         msg = self.extra
 
         @property
+        @functools.wraps(prop)
         def wrapped(*args, **kwargs):
             warnings.warn(msg, category=FutureWarning)
             return prop.fget(*args, **kwargs)
 
+        wrapped.__doc__ = self._update_doc(wrapped.__doc__)
+
         return wrapped
 
     def _update_doc(self, olddoc):
diff --git a/sklearn/utils/tests/test_deprecation.py b/sklearn/utils/tests/test_deprecation.py
@@ -19,6 +19,12 @@ class MockClass2:
     def method(self):
         pass
 
+    @deprecated("n_features_ is deprecated")  # type: ignore
+    @property
+    def n_features_(self):
+        """Number of input features."""
+        return 10
+
 
 class MockClass3:
     @deprecated()
@@ -55,3 +61,12 @@ def test_is_deprecated():
 
 def test_pickle():
     pickle.loads(pickle.dumps(mock_function))
+
+
+def test_deprecated_property_docstring_exists():
+    """Deprecated property contains the original docstring."""
+    mock_class_property = getattr(MockClass2, "n_features_")
+    assert (
+        "DEPRECATED: n_features_ is deprecated\n\n    Number of input features."
+        == mock_class_property.__doc__
+    )
