Repository: piskvorky/gensim

Issue:
Wrong return types in docstrings for wv.evaluate_word_analogies and wv.evaluate_word_pairs
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))`.


Discussion:
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?


I looked at the documentation for Numpy-style docstrings as well as examples from Numpy and Pandas<sup>[[1]](#pandas-docstring)</sup> 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.

<a name="#pandas-docstring" href="https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html#parameter-types">[1] pandas docstring guide # Parameter types</a> 

Resolving patch:
diff --git a/gensim/models/keyedvectors.py b/gensim/models/keyedvectors.py
--- a/gensim/models/keyedvectors.py
+++ b/gensim/models/keyedvectors.py
@@ -1069,7 +1069,7 @@ def evaluate_word_analogies(self, analogies, restrict_vocab=300000, case_insensi
         -------
         score : float
             The overall evaluation score on the entire evaluation set
-        sections : list of dict of {str : str or tuple of (str, str, str, str)}
+        sections : list of dict of {str : str or list of tuple of (str, str, str, str)}
             Results broken down by each section of the evaluation set. Each dict contains the name of the section
             under the key 'section', and lists of correctly and incorrectly predicted 4-tuples of words under the
             keys 'correct' and 'incorrect'.


Test patch: