Wrong return types in docstrings for wv.evaluate_word_analogies and wv.evaluate_word_pairs

[Stigjb]

This is the documented return type for KeyedVectors.evaluate_word_analogies:
https://github.com/RaRe-Technologies/gensim/blob/6a4424d3e465dea0afcddc4f4e2410cf0f52dba1/gensim/models/keyedvectors.py#L1070

The dicts in the second element of the return tuple have as values either a string or a list of 4-tuples. For instance:

{
    'section': 'family',
    'correct': [('he', 'she', 'dad', 'mom'), ...],
    'incorrect': [('man', 'woman', 'groom', 'bride'), ...]
}

So I believe the return value of evaluate_word_analogies is actually Tuple[float, List[Dict[str, Union[str, List[Tuple[str, str, str, str]]]]] (in PEP-484 style annotation).

Then, in KeyedVectors.evaluate_word_pairs, the documented return type is:
https://github.com/RaRe-Technologies/gensim/blob/6a4424d3e465dea0afcddc4f4e2410cf0f52dba1/gensim/models/keyedvectors.py#L1284

Here, the second and third elements of the return tuple are actually pairs of floats, since they are the values returned from scipy.stats.pearsonr and spearmanr, which return both the correlation and a p-value. I don't know whether the p-value should be discarded or the documented return type be updated to (float, (float, float), (float, float)).

[menshikh-iv]

Hello @Stigjb, thanks for the report

So I believe the return value of evaluate_word_analogies is actually Tuple[float, List[Dict[str, Union[str, List[Tuple[str, str, str, str]]]]] (in PEP-484 style annotation).

I would be happy to use PEP484 annotation style, but I'm not sure how to use it in docstring (we use sphinx & napoleon plugin for numpy-style docstrings), also, we can't annotate arguments directly in the definition using typing backport lib (because of no new syntax support). Have you any thought about it?

Of course, this is a bug in current return type and should be fixed, but maybe you have some good ideas how to apply PEP484 in our case?

[Stigjb]

I looked at the documentation for Numpy-style docstrings as well as examples from Numpy and Pandas^[1] with multiple return values, and think I found a way to describe these complex types better. See the PR.

The reason that I used PEP484 style in the original issue was just that it is the type annotation style I'm most fluent in, not a suggestion to switch over.

[1] pandas docstring guide # Parameter types

[Stigjb]

I found out that I got a detail wrong, please look at #2207 @menshikh-iv