Improve pytest.Config.getoption docstring (#12886)

Closes #10558.

---------

Co-authored-by: suspe <[email protected]>
(cherry picked from commit d8d607e)

AUTHORS

@@ -116,6 +116,7 @@ Dave Hunt
 David Díaz-Barquero
 David Mohr
 David Paul Röthlisberger
+David Peled
 David Szotten
 David Vierra
 Daw-Ran Liou

changelog/10558.doc.rst

@@ -0,0 +1 @@
+Fix ambiguous docstring of :func:`pytest.Config.getoption`.

src/_pytest/config/__init__.py

@@ -1682,11 +1682,12 @@ def _get_override_ini_value(self, name: str) -> str | None:
     def getoption(self, name: str, default=notset, skip: bool = False):
         """Return command line option value.
 
-        :param name: Name of the option.  You may also specify
+        :param name: Name of the option. You may also specify
             the literal ``--OPT`` option instead of the "dest" option name.
-        :param default: Default value if no option of that name exists.
-        :param skip: If True, raise pytest.skip if option does not exists
-            or has a None value.
+        :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.
         """
         name = self._opt2dest.get(name, name)
         try:

testing/test_config.py

@@ -636,7 +636,7 @@ def test_config_trace(self, pytester: Pytester) -> None:
         assert len(values) == 1
         assert values[0] == "hello [config]\n"
 
-    def test_config_getoption(self, pytester: Pytester) -> None:
+    def test_config_getoption_declared_option_name(self, pytester: Pytester) -> None:
         pytester.makeconftest(
             """
             def pytest_addoption(parser):
@@ -648,6 +648,18 @@ def pytest_addoption(parser):
             assert config.getoption(x) == "this"
         pytest.raises(ValueError, config.getoption, "qweqwe")
 
+        config_novalue = pytester.parseconfig()
+        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
+
+    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
+
     def test_config_getoption_unicode(self, pytester: Pytester) -> None:
         pytester.makeconftest(
             """
@@ -675,12 +687,6 @@ def pytest_addoption(parser):
         with pytest.raises(pytest.skip.Exception):
             config.getvalueorskip("hello")
 
-    def test_getoption(self, pytester: Pytester) -> None:
-        config = pytester.parseconfig()
-        with pytest.raises(ValueError):
-            config.getvalue("x")
-        assert config.getoption("x", 1) == 1
-
     def test_getconftest_pathlist(self, pytester: Pytester, tmp_path: Path) -> None:
         somepath = tmp_path.joinpath("x", "y", "z")
         p = tmp_path.joinpath("conftest.py")