Add support and tests for @return Promise<T>

[lovell]

Hello, this small PR allows a function to return a Promise that will resolve to a given Type, e.g. @return {Promise<Object>}.

Prior to this PR, use of @returns {Promise<T>} mapped to the invalid Promise.<T>

Technically this will also add support for AnyContainer<T>, but the test case is specific to the use of a Promise as that's the problem I ran into - see lovell/sharp#472 (comment)

[cryptiklemur]

Would love to see this

[englercj]

I think the problem is even larger than this, the question really is how to support built-in, non-primitive, types. That list of types is different depending on the env you build for.

In v2, it will try to lookup a ""Promise." type in the jsdoc information. When it can't find that it will log a warning and fall back to any. Obviously this is not desired, but I'm not sure what the best way is to differentiate between an unresolved object we should warn about and a built-in we should output as-is.

[stereobooster]

Alternative way is to check if it is present in TypeScript definitions, like "@types/node": "^8.0.46",.

Because tsc (starting from 2.3) can be used to validate types based on jsdoc it will require those definitions too.

[englercj]

Currently a basic version of built-in types is working in v2. Still need to add support for generic promises.

[lovell]

Closing as there seems to be progress being made on this (plus this PR is very much out of date).