Remove async prefix from JSDOC?

[inikulin]

I'm wondering should we remove async prefix from JSDOC and use @returns Promise<T> instead?
For me it's seems more semantically correct. Moreover, in client code we don't have async funcs and for the non-ES6 code (e.g. in tests) this funcitons looks like regular funcs which returns Promises.
\cc @AndreyBelym @AlexanderMoskovkin @VasilyStrelyaev

[AlexanderMoskovkin]

We were thinking about that. But I think it may be hard to describe that the getInstallations function returns a Promise that "returns" BrowserInfo with jsdoc. While async getInstallations() ⇒ Object.<string, BrowserInfo> looks clearly.

[inikulin]

Promise<Dictionary<string, BrowserInfo>>? However, it's more clear when current implementation, anyway then we will have Hammerhead client API described, we'll not be able to use async

[VasilyStrelyaev]

We don't have to use wordy phrasing just because we formally write Promise<Object.<string, BrowserInfo>>. We can say a kind of 'returns [smth] through a Promise'.
If it's technically more correct and helps us avoid confusion in certain cases - than let's return back to Promises in JSDOC.

[inikulin]

We can say a kind of 'returns [smth] through a Promise'.

We can't. We should use JSDOC notation

[inikulin]

Plus: it's not true that we return e.g. browserInfo from async func. We return Promise. So, current solution is misleading at least.

[VasilyStrelyaev]

We can't. We should use JSDOC notation

If we change the phrase 'returns a Promise that returns a list' to 'returns a list through a Promise' - do we really break a notation?

[inikulin]

@VasilyStrelyaev you don't get it. We don't have phrases, we can use just types, e.g.: Promise<string>

[VasilyStrelyaev]

we must be discussing different things...

[inikulin]

@VasilyStrelyaev then can you clarify your statement pls )

[VasilyStrelyaev]

@inikulin ok, then...
first thing I don't get is what you mean when you say "we don't have phrases only types"
what I see is that we can add descriptions to virtually everything
http://usejsdoc.org/tags-returns.html

[inikulin]

@VasilyStrelyaev I thought we were talking about return type which is the subject of debate in this issue.

[VasilyStrelyaev]

@inikulin yep, and then @AlexanderMoskovkin expressed a doubt that we can convey everything with a return type. Which, my point, is not a problem if (a) our return type is formally correct and (b) we add a clear description.
However, I misread @AlexanderMoskovkin 's message and thought he said we would have to use long and vague descriptions. That's where all the confusion in this thread came from.