Refactor: suggestions from @hakonanes

CHANGELOG.rst

@@ -15,7 +15,7 @@ Added
 - Explicit support for Python 3.11.
 - Added deprecation tools for deprecating functions and arguments.
 - Added Pre-Commit for code formatting.
-
+- Added deprecation tools for deprecating functions, parameters, methods, and properties.
 
 Changed
 -------

CONTRIBUTING.rst

@@ -140,15 +140,15 @@ with a possible alternative to be used.
 The decorator should be placed right above the object signature to be deprecated::
 
 .. code-block:: python
-    >>> from diffsims.utils._deprecated import deprecate
-    >>> @deprecate(since=0.8, removal=0.9, alternative="bar")
-    >>> def foo(self, n):
-    >>>     return n + 1
-
-    >>> @property
-    >>> @deprecate(since=0.9, removal=0.10, alternative="another", is_function=True)
-    >>> def this_property(self):
-    >>>     return 2
+    from diffsims.utils._deprecated import deprecate
+    @deprecate(since=0.8, removal=0.9, alternative="bar")
+    def foo(self, n):
+        return n + 1
+
+    @property
+    @deprecate(since=0.9, removal=0.10, alternative="another", is_function=True)
+    def this_property(self):
+        return 2
 
 
 Build and write documentation

diffsims/utils/_deprecated.py

@@ -18,8 +18,10 @@
 
 
 """Helper functions and classes for managing diffsims.
+
 This module and documentation is only relevant for diffsims developers,
 not for users.
+
 .. warning:
     This module and its submodules are for internal use only.  Do not
     use them in your own code. We may change the API at any time with no
@@ -37,11 +39,10 @@
 class deprecated:
     """Decorator to mark deprecated functions with an informative
     warning.
+
     Adapted from
-    `scikit-image
-    <https://github.com/scikit-image/scikit-image/blob/main/skimage/_shared/utils.py>`_
-    and `matplotlib
-    <https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/_api/deprecation.py>`_.
+    `scikit-image<https://github.com/scikit-image/scikit-image/blob/main/skimage/_shared/utils.py>`_
+    and `matplotlib<https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/_api/deprecation.py>`_.
     """
 
     def __init__(
@@ -52,6 +53,7 @@ def __init__(
         removal: Union[str, int, float, None] = None,
     ):
         """Visible deprecation warning.
+
         Parameters
         ----------
         since
@@ -116,6 +118,7 @@ def wrapped(*args, **kwargs):
 class deprecated_argument:
     """Decorator to remove an argument from a function or method's
     signature.
+
     Adapted from `scikit-image
     <https://github.com/scikit-image/scikit-image/blob/main/skimage/_shared/utils.py>`_.
     """