DOC/Discussion: Update docstrings guide to include guidance for edge cases

[josibake]

There are a few edge cases where there is not sufficient guidance in the docstrings on how to proceed. For example, if a parameter argument takes a list of values but the list is sufficiently long, it is not clear how to properly format (see #28739).

Opening this as a placeholder to document edge cases encountered while cleaning up docstrings and agree on what the convention should be.

[josibake]

long list of accepted values

normally, lists of known values are documented as:

unit : {'day', 'month', 'year'}, default 'day'
    Specify unit of time.

but if the list is long (say, greater than 5), the convention should be:

unit : str, default 'day'
    Specify unit of time.

    Possible values:
        * 'day', 'month', or 'year'
        * 'hour', 'minute', 'second', or 'nanosecond'
        ...