docs: fix misleading docstring about default vs skip=True in getoption

changelog/13879.doc.rst

@@ -0,0 +1,9 @@
+Clarified `pytest/Config.getoption` docstring to make the exceptional behavior of `default` with `skip=True` explicit.
+
+The previous docstring implied:
+
+- The `default` parameter is ignored when the option is declared.
+
+But actual behavior is:
+
+- The `default` is **not ignored** even if the option is declared, when `skip=True` and the option has `None` value.

src/_pytest/config/__init__.py

@@ -1845,12 +1845,15 @@ def _getconftest_pathlist(
     def getoption(self, name: str, default: Any = notset, skip: bool = False):
         """Return command line option value.
 
-        :param name: Name of the option. You may also specify
-            the literal ``--OPT`` option instead of the "dest" option name.
-        :param default: Fallback value if no option of that name is **declared** via :hook:`pytest_addoption`.
-            Note this parameter will be ignored when the option is **declared** even if the option's value is ``None``.
-        :param skip: If ``True``, raise :func:`pytest.skip` if option is undeclared or has a ``None`` value.
-            Note that even if ``True``, if a default was specified it will be returned instead of a skip.
+        :param name:
+            Name of the option. You may also specify the literal ``--OPT`` option instead of the "dest" option name.
+        :param default:
+            Fallback value if the option is not available.
+            Ignored when the option has been declared (even if its value is ``None``), unless ``skip=True``.
+        :param skip:
+            If ``True``, call :func:`pytest.skip` if the option is undeclared or ``None``.
+            Note that when ``skip=True`` and the ``default`` parameter is provided (even ``None``),
+            the default value is returned instead of skipping.
         """
         name = self._opt2dest.get(name, name)
         try:

testing/test_config.py

@@ -768,13 +768,15 @@ def pytest_addoption(parser):
         assert config_novalue.getoption("hello") is None
         assert config_novalue.getoption("hello", default=1) is None
         assert config_novalue.getoption("hello", default=1, skip=True) == 1
+        assert config_novalue.getoption("hello", default=None, skip=True) is None
 
     def test_config_getoption_undeclared_option_name(self, pytester: Pytester) -> None:
         config = pytester.parseconfig()
         with pytest.raises(ValueError):
             config.getoption("x")
         assert config.getoption("x", default=1) == 1
         assert config.getoption("x", default=1, skip=True) == 1
+        assert config.getoption("x", default=None, skip=True) is None
 
     def test_config_getoption_unicode(self, pytester: Pytester) -> None:
         pytester.makeconftest(