Add support for Promises

[albertorestifo]

There should be a special tag to easily document promises.

As a reference, see the discussion at the JSDoc repo: jsdoc/jsdoc#509

[tmcw]

I'm open to the idea, but ideally this first lands upstream in JSDoc - our strategy so far is to always follow existing JSDoc standards.

[albertorestifo]

What about making it an internal plugin that you can activate via configuration flag?

That way it would not be official but still be there as an option. I don't think JSDoc will add them anytime soon, and Promises are used quite a bit today.

[tmcw]

Okay, agreed - I think upstream we can implement a rule-adding interface to doctrine, the JSDoc syntax parser.

[tmcw]

On further consideration, Promise<resultType> is a perfectly good way to document promises, and the thread on the jsdoc side never found resolution. I'm happy to accept a PR from someone with the vision who wants to implement this, but for my scope I'm going to accept Promise<resultType> as a good-enough solution.

[arv]

Agreed. Promise<T> is the way to do this and is widely used in lots of projects...