Add deprecation notice to docstring

More for the documentation to reflect this than anything else

flaskbb/deprecation.py

@@ -75,6 +75,15 @@ def deprecated(message="", category=RemovedInFlaskBB3):
         if message:
             warning = "{} {}".format(warning, message)
 
+        docstring = f.__doc__
+
+        if docstring:
+            docstring = "\n".join([docstring, warning])
+        else:
+            docstring = warning
+
+        f.__doc__ = docstring
+
         @wraps(f)
         def wrapper(*a, **k):
             frame = inspect.currentframe().f_back

tests/unit/test_deprecation.py

@@ -15,6 +15,9 @@ def only_a_drill():
 # TODO(anr): Make the parens optional
 @deprecated()
 def default_deprecation():
+    """
+    Existing docstring
+    """
     pass
 
 
@@ -30,7 +33,8 @@ class TestDeprecation(object):
         assert recwarn[0].filename == __file__
         # assert on the next line is conditional on the position of the call
         # to default_deprecation please don't jiggle it around too much
-        assert recwarn[0].lineno == 25
+        assert recwarn[0].lineno == 28
+        assert "only_a_drill is deprecated" in only_a_drill.__doc__
 
     def tests_emits_specialized_message(self, recwarn):
         warnings.simplefilter("default", RemovedInFlaskBB3)
@@ -57,6 +61,12 @@ class TestDeprecation(object):
 
         assert len(recwarn) == 1
 
+    def test_adds_to_existing_docstring(self, recwarn):
+        docstring = default_deprecation.__doc__
+
+        assert "Existing docstring" in docstring
+        assert "default_deprecation is deprecated" in docstring
+
     @deprecated()
     def deprecated_instance_method(self):
         pass