DOC: update the pd.Index.contains docstring

[dajcs]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
###################### Docstring (pandas.Index.contains)  ######################
################################################################################

Return a boolean if key is in the index.

This function returns True if key is in the index and
returns False if key is not in index.

Parameters
----------
key : immutable object
    Key to be searched.

Returns
-------
bool
    Result of the key search.

Notes
-----
    CategoricalIndex is a sub-class of Index.

Examples
--------
>>> pd.CategoricalIndex([2000, 2001, 2012]).contains(2001)
True
>>> pd.CategoricalIndex([2000, 2001, 2012]).contains(2222)
False

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        See Also section not found

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

See Also missing because we haven't found similar functions

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[TomAugspurger]

I think this extended summary can be removed.

[TomAugspurger]

can remove immutable, it could be anything.

[dajcs]

can't be anything:
pd.CategoricalIndex([2000, 2001, 2012]).contains([1,2])
TypeError: unhashable type: 'list'

[TomAugspurger]

Don't think you need this Notes section.

[TomAugspurger]

Could you add a See Also with Index.isin

[dajcs]

this note is because of shared documentation between Index and CategoricalIndex

[TomAugspurger]

Best to just use a regular Index here, not a CategoricalIndex.

[dajcs]

pd.Index.contains and pd.CategoricalIndex.contains have shared documentation
and a CategoricalIndex example is valid for Index but not the other way around since CategoricalIndex is a sub-class of Index

[jreback]

yeah for this particular case I would separate the doc-strings, IOW 1 more Index and a separate one for CategoricalIndex. Can use a shared doc if that works (with templates)

[jreback]

yeah for this particular case I would separate the doc-strings, IOW 1 more Index and a separate one for CategoricalIndex. Can use a shared doc if that works (with templates)

[jorisvandenbossche]

@dajcs do you have time to update the PR based on the feedback?

[TanyaaCJain]

I am working to update this PR in accordance with the reviews made to it and match it to the Pandas docstring standards.

[datapythonista]

Superseded by #23100 and #23107