DOC Improve docstrings for scikit-learn configuration functions (scikit-learn#31486)

Co-authored-by: Adrin Jalali <adrin.jalali@gmail.com>

Author: StefanieSenger

sklearn/_config.py

@@ -33,7 +33,10 @@ def _get_threadlocal_config():
 
 
 def get_config():
-    """Retrieve current values for configuration set by :func:`set_config`.
+    """Retrieve the current scikit-learn configuration.
+
+    This reflects the effective global configurations as established by default upon
+    library import, or modified via :func:`set_config` or :func:`config_context`.
 
     Returns
     -------
@@ -71,6 +74,15 @@ def set_config(
 ):
     """Set global scikit-learn configuration.
 
+    These settings control the behaviour of scikit-learn functions during a library
+    usage session. Global configuration defaults (as described in the parameter list
+    below) take effect when scikit-learn is imported.
+
+    This function can be used to modify the global scikit-learn configuration at
+    runtime. Passing `None` as an argument (the default) leaves the corresponding
+    setting unchanged. This allows users to selectively update the global configuration
+    values without affecting the others.
+
     .. versionadded:: 0.19
 
     Parameters
@@ -79,7 +91,7 @@ def set_config(
         If True, validation for finiteness will be skipped,
         saving time, but leading to potential crashes. If
         False, validation for finiteness will be performed,
-        avoiding error.  Global default: False.
+        avoiding error. Global default: False.
 
         .. versionadded:: 0.19
 
@@ -96,20 +108,22 @@ def set_config(
         values will be printed when printing an estimator. For example,
         ``print(SVC())`` while True will only print 'SVC()' while the default
         behaviour would be to print 'SVC(C=1.0, cache_size=200, ...)' with
-        all the non-changed parameters.
+        all the non-changed parameters. Global default: True.
 
         .. versionadded:: 0.21
+        .. versionchanged:: 0.23
+           Global default configuration changed from False to True.
 
     display : {'text', 'diagram'}, default=None
         If 'diagram', estimators will be displayed as a diagram in a Jupyter
         lab or notebook context. If 'text', estimators will be displayed as
-        text. Default is 'diagram'.
+        text. Global default: 'diagram'.
 
         .. versionadded:: 0.23
 
     pairwise_dist_chunk_size : int, default=None
         The number of row vectors per chunk for the accelerated pairwise-
-        distances reduction backend. Default is 256 (suitable for most of
+        distances reduction backend. Global default: 256 (suitable for most of
         modern laptops' caches and architectures).
 
         Intended for easier benchmarking and testing of scikit-learn internals.
@@ -130,7 +144,7 @@ def set_config(
 
     array_api_dispatch : bool, default=None
         Use Array API dispatching when inputs follow the Array API standard.
-        Default is False.
+        Global default: False.
 
         See the :ref:`User Guide <array_api>` for more details.
 
@@ -147,6 +161,8 @@ def set_config(
         - `"polars"`: Polars output
         - `None`: Transform configuration is unchanged
 
+        Global default: "default".
+
         .. versionadded:: 1.2
         .. versionadded:: 1.4
             `"polars"` option was added.
@@ -161,13 +177,16 @@ def set_config(
         - `False`: Metadata routing is disabled, use the old syntax.
         - `None`: Configuration is unchanged
 
+        Global default: False.
+
         .. versionadded:: 1.3
 
     skip_parameter_validation : bool, default=None
         If `True`, disable the validation of the hyper-parameters' types and values in
         the fit method of estimators and for arguments passed to public helper
         functions. It can save time in some situations but can lead to low level
         crashes and exceptions with confusing error messages.
+        Global default: False.
 
         Note that for data parameters, such as `X` and `y`, only type validation is
         skipped but validation with `check_array` will continue to run.
@@ -225,46 +244,53 @@ def config_context(
     enable_metadata_routing=None,
     skip_parameter_validation=None,
 ):
-    """Context manager for global scikit-learn configuration.
+    """Context manager to temporarily change the global scikit-learn configuration.
+
+    This context manager can be used to apply scikit-learn configuration changes within
+    the scope of the with statement. Once the context exits, the global configuration is
+    restored again.
+
+    The default global configurations (which take effect when scikit-learn is imported)
+    are defined below in the parameter list.
 
     Parameters
     ----------
     assume_finite : bool, default=None
         If True, validation for finiteness will be skipped,
         saving time, but leading to potential crashes. If
         False, validation for finiteness will be performed,
-        avoiding error. If None, the existing value won't change.
-        The default value is False.
+        avoiding error. If None, the existing configuration won't change.
+        Global default: False.
 
     working_memory : int, default=None
         If set, scikit-learn will attempt to limit the size of temporary arrays
         to this number of MiB (per job when parallelised), often saving both
         computation time and memory on expensive operations that can be
-        performed in chunks. If None, the existing value won't change.
-        The default value is 1024.
+        performed in chunks. If None, the existing configuration won't change.
+        Global default: 1024.
 
     print_changed_only : bool, default=None
         If True, only the parameters that were set to non-default
         values will be printed when printing an estimator. For example,
         ``print(SVC())`` while True will only print 'SVC()', but would print
         'SVC(C=1.0, cache_size=200, ...)' with all the non-changed parameters
-        when False. If None, the existing value won't change.
-        The default value is True.
+        when False. If None, the existing configuration won't change.
+        Global default: True.
 
         .. versionchanged:: 0.23
-           Default changed from False to True.
+           Global default configuration changed from False to True.
 
     display : {'text', 'diagram'}, default=None
         If 'diagram', estimators will be displayed as a diagram in a Jupyter
         lab or notebook context. If 'text', estimators will be displayed as
-        text. If None, the existing value won't change.
-        The default value is 'diagram'.
+        text. If None, the existing configuration won't change.
+        Global default: 'diagram'.
 
         .. versionadded:: 0.23
 
     pairwise_dist_chunk_size : int, default=None
         The number of row vectors per chunk for the accelerated pairwise-
-        distances reduction backend. Default is 256 (suitable for most of
+        distances reduction backend. Global default: 256 (suitable for most of
         modern laptops' caches and architectures).
 
         Intended for easier benchmarking and testing of scikit-learn internals.
@@ -285,7 +311,7 @@ def config_context(
 
     array_api_dispatch : bool, default=None
         Use Array API dispatching when inputs follow the Array API standard.
-        Default is False.
+        Global default: False.
 
         See the :ref:`User Guide <array_api>` for more details.
 
@@ -302,6 +328,8 @@ def config_context(
         - `"polars"`: Polars output
         - `None`: Transform configuration is unchanged
 
+        Global default: "default".
+
         .. versionadded:: 1.2
         .. versionadded:: 1.4
             `"polars"` option was added.
@@ -316,13 +344,16 @@ def config_context(
         - `False`: Metadata routing is disabled, use the old syntax.
         - `None`: Configuration is unchanged
 
+        Global default: False.
+
         .. versionadded:: 1.3
 
     skip_parameter_validation : bool, default=None
         If `True`, disable the validation of the hyper-parameters' types and values in
         the fit method of estimators and for arguments passed to public helper
         functions. It can save time in some situations but can lead to low level
         crashes and exceptions with confusing error messages.
+        Global default: False.
 
         Note that for data parameters, such as `X` and `y`, only type validation is
         skipped but validation with `check_array` will continue to run.