--- a/src/pyams_utils/decorator.py	Wed Nov 20 19:26:23 2019 +0100
+++ b/src/pyams_utils/decorator.py	Fri Nov 22 18:51:37 2019 +0100
@@ -16,22 +16,43 @@
 deprecated.
 """
 
-__docformat__ = 'restructuredtext'
-
 import functools
 import warnings
 
+__docformat__ = 'restructuredtext'
+
 
 def deprecated(*msg):
     """This is a decorator which can be used to mark functions as deprecated.
 
     It will result in a warning being emitted when the function is used.
+
+    >>> from pyams_utils.context import capture_stderr
+    >>> from pyams_utils.decorator import deprecated
+
+    >>> @deprecated
+    ... def my_function(value):
+    ...     return value
+
+    >>> with capture_stderr(my_function, 1) as err:
+    ...     print(err.split('\\n')[0])
+    <doctest ... DeprecationWarning: Function my_function is deprecated.
+
+    >>> @deprecated('Deprecation message')
+    ... def my_function_2(value):
+    ...     return value
+
+    >>> with capture_stderr(my_function_2, 2) as err:
+    ...     print(err.split('\\n')[0])
+    <doctest ... DeprecationWarning: Function my_function_2 is deprecated. Deprecation message
     """
 
     def decorator(func):
+        """Actual decorator"""
 
         @functools.wraps(func)
         def new_func(*args, **kwargs):
+            """Wrapped decorator function"""
             warnings.warn_explicit("Function %s is deprecated. %s" % (func.__name__, message),
                                    category=DeprecationWarning,
                                    filename=func.__code__.co_filename,