That's great that PyMEL has that documentation version of their code. Lots of people have lots of ideas about how to make something like that work well, though there's no consensus yet.
Our code analyzer works best with code - we pay very little attention to docstrings unless they're in a .pyd file - so something like this is a better stub for us:
def optionMenu(alwaysCallChangeCommand=True, annotation="", backgroundColor=(1.0, 1.0, 1.0), ...):
(You can even have multiple
s in there for different return types. It's not a syntax error, so we'll analyse it fine, even if the code is unreachable.)
It's possible that the other version of PyMEL will give you better completions in PTVS, even if it's lacking docstrings. Modifying the specializations may also help, but that's a much bigger task than you're probably expecting :)
I don't think we're ever likely to feed information from docstrings into our analysis - most docstrings aren't good enough, which means we either get things wrong or have to force people to manually include/exclude functions/modules/etc. from that analysis,
neither of which I want to do - but we always have handled default argument values and trivial return types well.