Merge pull request #25451 from CAM-Gerlach/spyder-api-revise-config-docstrings-master

PR: Add & revise docstrings in the `spyder.api.config` module

Author: ccordoba12

spyder/api/config/decorators.py

@@ -1,63 +1,99 @@
-# -*- coding: utf-8 -*-
+# -----------------------------------------------------------------------------
+# Copyright (c) 2021- Spyder Project Contributors
 #
-# Copyright © Spyder Project Contributors
-# Licensed under the terms of the MIT License
-# (see spyder/__init__.py for details)
+# Released under the terms of the MIT License
+# (see LICENSE.txt in the project root directory for details)
+# -----------------------------------------------------------------------------
 
 """
 Spyder API helper decorators.
 """
 
+from __future__ import annotations
+
 # Standard library imports
 import functools
-from typing import Callable, Optional, Union, List
+import sys
+from collections.abc import Callable
+from typing import Union
+
+if sys.version_info < (3, 10):
+    from typing_extensions import TypeAlias
+else:
+    from typing import TypeAlias  # noqa: ICN003
 
 # Local imports
 from spyder.config.types import ConfigurationKey
 
 
-ConfigurationKeyList = List[ConfigurationKey]
-ConfigurationKeyOrList = Union[ConfigurationKeyList, ConfigurationKey]
+ConfigurationKeyList: TypeAlias = list[ConfigurationKey]
+"""Type alias for a list of string/string tuple keys of Spyder config options.
+
+A :class:`list` of :class:`spyder.config.types.ConfigurationKey`\\s.
+"""
+
+ConfigurationKeyOrList: TypeAlias = Union[
+    ConfigurationKeyList, ConfigurationKey
+]
+"""Type alias for either a list of config keys or a single key.
+
+Union of types :class:`ConfigurationKeyList` and
+:class:`spyder.config.types.ConfigurationKey`.
+"""
 
 
-def on_conf_change(func: Callable = None,
-                   section: Optional[str] = None,
-                   option: Optional[ConfigurationKeyOrList] = None) -> Callable:
+def on_conf_change(
+    func: Callable | None = None,
+    section: str | None = None,
+    option: ConfigurationKeyOrList | None = None,
+) -> Callable:
     """
-    Method decorator used to handle changes on the configuration option
-    `option` of the section `section`.
+    Decorator to handle changing a config option in a given section.
 
-    The methods that use this decorator must have the following signature
-    `def method(self, value)` when observing a single value or the whole
-    section and `def method(self, option, value): ...` when observing
-    multiple values.
+    The methods that use this decorator must have the signature
+
+    .. code-block:: python
+
+        def method(self, value: Any):
+            ...
+
+    when observing a single value or the whole section, and
+
+    .. code-block:: python
+
+        def method(self, option: ConfigurationKeyOrList | None, value: Any):
+            ...
+
+    when observing multiple values.
 
     Parameters
     ----------
-    func: Callable
-        Method to decorate. Given by default when applying the decorator.
-    section: Optional[str]
-        Name of the configuration whose option is going to be observed for
-        changes. If None, then the `CONF_SECTION` attribute of the class
-        where the method is defined is used.
-    option: Optional[ConfigurationKeyOrList]
-        Name/tuple of the option to observe or a list of name/tuples if the
-        method expects updates from multiple keys. If None, then all changes
-        on the specified section are observed.
+    func: Callable | None, optional
+        Method to decorate, passed automatically when applying the decorator.
+    section: str | None, optional
+        Name of the configuration section to observe for changes.
+        If ``None``, then the ``CONF_SECTION`` attribute of the class
+        where the method defined is used.
+    option: ConfigurationKeyOrList | None, optional
+        Name (:class:`str` / :class:`tuple` of :class:`str`) of the option
+        to observe, or a list of names if the method expects updates from
+        multiple keys. If ``None``, then all changes to options in the
+        specified section are observed.
 
     Returns
     -------
     func: Callable
-        The same method that was given as input.
+        The method passed as ``func`` with the config listener set up.
     """
     if func is None:
         return functools.partial(
-            on_conf_change, section=section, option=option)
+            on_conf_change, section=section, option=option
+        )
 
     if option is None:
         # Use special __section identifier to signal that the function
         # observes any change on the section options.
-        option = '__section'
+        option = "__section"
 
     info = []
     if isinstance(option, list):