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

[midoriao]

This PR clarifies the pytest.Config.getoption docstring to make the exceptional behavior of default with skip=True explicit.

Also adds a small test verifying that behavior.

Stituation before this change

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.

This can be reproduced by the following test case (already existing in testing/test_config.py):

def test_config_getoption_declared_option_name(self, pytester: Pytester) -> None:
	pytester.makeconftest(
		"""
		def pytest_addoption(parser):
			parser.addoption("--hello", "-X", dest="hello")
	"""
	)
	config_novalue = pytester.parseconfig()
	assert config_novalue.getoption("hello", default=1, skip=True) == 1

Rationale

The getoption() behavior involves multiple conditions (whether the option is declared or not, None or not, default, skip), which previously made the docstring easy to misinterpret. This PR avoids multiple "note that ..." caveats and keeps each parameter’s description self-contained and readable.

• The docstring now describes the skip=True special case in plain language.
• The misleading reference to the pytest_addoption hook was removed, since this method’s behavior is independent of how the option was added.
• The emphasis markup of **declared** was removed.
  • It was intended to hint that an option might be declared but still have a None value (context: Improve pytest.Config.getoption docstring #12886). The new wording states this condition explicitly.
• Clarify the case when default=None and skip=True.

Notes

No behavior change; documentation and test addition only.
Related historical issue: #10558

[bluetech]

I'm curious how you came across this, is there actually a use case for passing both default and skip? I'm probably missing something but I don't see it.

I'm also curious why skip has this None behavior. Maybe it's intended to catch the case where the flag wasn't passed, but only accidentally catches the case that it was passed just without a value?

[midoriao]

I also don’t think there is a practical use case for specifying both at the same time. The intention of this PR is simply to correct a misleading description.

I ran into this simply by reading the API reference and trying to understand what actual role of default is. The description was complicated enough that I went to the implementation to double-check. That’s when I noticed the gap.

I'm also curious why skip has this None behavior. Maybe it's intended to catch the case where the flag wasn't passed, but only accidentally catches the case that it was passed just without a value?

As far as I can tell, this behavior was first discussed in detail in #10558. The conclusion there seemed to be that the behavior is established and not considered a bug, and that it should be documented clearly instead of changed.

Given the unusual behavior, it might be clearer to keep the parameter descriptions simple and move the detail into a .. note:: section.

Here is a possible wording:

:param default:
    Value to return when the option is undeclared (a declared option with value
    ``None`` is *not* considered undeclared).

:param skip:
    If True, raise `pytest.skip` when the option is undeclared or has a None value.

.. note::
    ``default`` and ``skip=True`` use different rules for what counts as a
    "missing value":

    * ``default`` applies only when the option is undeclared.  
    * ``skip=True`` treats both an undeclared option and None value as missing.

    When both parameters are used together, a provided ``default`` is returned
    instead of skipping. This behavior exists for historical and backward-compatibility reasons.
    See issue #10558 for background.