DOC102 false positives

[ntBre]

There were two remaining false positives found in the ecosystem check on #20376.

• disnake/client.py:814:9: DOC102 Documented parameter Example is not in the function's signature
  We look for a section called Examples, but I think it would be worth allowing singular Example too. I think this one is not specific to DOC102 and can affect other rules.
• superset/async_events/api.py:57:11: DOC102 Documented parameter responses is not in the function's signature
  This and several other superset errors are from docstrings like

          """
        Read off of the Redis async events stream, using the user's JWT token and
        optional query params for last event received.
        ---
        get:
          summary: Read off of the Redis events stream
          description: >-
            Reads off of the Redis events stream, using the user's JWT token and
            optional query params for last event received.
          parameters:
          - in: query
            name: last_id
            description: Last ID received by the client
            schema:
                type: string
          responses:
            200:

  which I guess looks like YAML. I feel like we could do something like not process sub-sections under an unknown heading to filter this out, but I haven't taken a closer look.

[augustelalande]

FYI for the second case, it is not an unknown heading. The problem is that we recognize parameters: as a valid heading.

[pep-sanwer]

A few more false positives related to less commonly used numpy docstring sections

From my testing it looks like the following valid sections are not being recognized as sections:

• Receives
• Warns
• Warnings

---

Given example.py like:

def bad_doc102(x: int) -> int:
    """
    Show a `Warnings` DOC102 false positive.

    Parameters
    ----------
    x : int

    Warnings
    --------
    This function demonstrates a DOC102 false positive

    Returns
    -------
    int
    """
    return x

results in the false positive

✗ ruff check example.py
example.py:
  9:5 DOC102 Documented parameter `Warnings` is not in the function's signature

Found 1 error.

---

Given example.py like:

def bad_doc102(x: int) -> int:
    """
    Show another `Warnings` DOC102 false positive.

    Parameters
    ----------
    x : int

    Raises
    ------
    ValueError
        If `x` is zero

    Warnings
    --------
    This function demonstrates a DOC102 false positive

    Returns
    -------
    int
    """
    if x == 0:
        msg = "x cannot be zero"
        raise ValueError(msg)

    return x

results in the false positive

✗ ruff check example.py
example.py:
  2:5 DOC502 Raised exceptions are not explicitly raised: `Warnings`, `--------`, `This function demonstrates a DOC102 false positive`

Found 1 error.

[augustelalande]

I can make a quick PR to add those