New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documenting the type of a value wrapped by a promise in async functions #9435

Open
cboulanger opened this Issue Nov 30, 2017 · 7 comments

Comments

Projects
None yet
3 participants
@cboulanger
Contributor

cboulanger commented Nov 30, 2017

Async functions always return a promise, so there is no need to provide a @return {Promise} JSDoc as it is implicit in the async keyword. However, an API consumer wants to know what type of value is wrapped in the Promise (== what type of value it resolves to). Also, this should be displayed in the new API viewer. The question has been debated in the JSDoc community but no consensus has been reached. Possible candidates are @promise {Type}, @return {Promise<Type>}, @resolves {Type}.

@derrell

This comment has been minimized.

Show comment
Hide comment
@derrell

derrell Nov 30, 2017

Member

And let's not forget that we need to document a promise that is an argument to a function as well, so:

@param {???}

possibly this, but it's really ugly IMO:

@param {Promise<qx.data.Array, Error>}
Member

derrell commented Nov 30, 2017

And let's not forget that we need to document a promise that is an argument to a function as well, so:

@param {???}

possibly this, but it's really ugly IMO:

@param {Promise<qx.data.Array, Error>}
@derrell

This comment has been minimized.

Show comment
Hide comment
@derrell

derrell Nov 30, 2017

Member

And if we do that, then the just-as-ugly return documentation should probably be used

@return {Promise<qx.data.Array, Error>}

but I have a strong preference for replacing @return with @promise for async functions.

Member

derrell commented Nov 30, 2017

And if we do that, then the just-as-ugly return documentation should probably be used

@return {Promise<qx.data.Array, Error>}

but I have a strong preference for replacing @return with @promise for async functions.

@johnspackman

This comment has been minimized.

Show comment
Hide comment
@johnspackman

johnspackman Nov 30, 2017

Member

if the function is written as async (in the ES6 sense of async function blah) then the jsdoc could show the value returned when resolved, but for functions which are written the old fashioned way I've parenthesised it, eg:

members: {
  /**
   * Does a thing
   * @return {Boolean} true
   */
  thisThing: async function() {
    return new qx.Promise(resolve => resolve(true));
  },

  /**
   * Does another thing
   * @return {qx.Promise(Boolean)} false
   */
  thatThing: function() {
    return new qx.Promise(resolve => resolve(true));
  }

The advantage of this is that the generator does not need to be modified to support it, and the compiler can add output to flag that the function is ES6 async

Member

johnspackman commented Nov 30, 2017

if the function is written as async (in the ES6 sense of async function blah) then the jsdoc could show the value returned when resolved, but for functions which are written the old fashioned way I've parenthesised it, eg:

members: {
  /**
   * Does a thing
   * @return {Boolean} true
   */
  thisThing: async function() {
    return new qx.Promise(resolve => resolve(true));
  },

  /**
   * Does another thing
   * @return {qx.Promise(Boolean)} false
   */
  thatThing: function() {
    return new qx.Promise(resolve => resolve(true));
  }

The advantage of this is that the generator does not need to be modified to support it, and the compiler can add output to flag that the function is ES6 async

@cboulanger

This comment has been minimized.

Show comment
Hide comment
@cboulanger

cboulanger Nov 30, 2017

Contributor

A lot to be said for each of these solutions, and yet none seems a natural fit. No wonder the JSDoc people haven't come up with a convention yet.

I think I like @return {Promise(Boolean)} best even though the round parentheses kind of suggest similarity to method signature. I think @return {Boolean} is misleading. Async functions return Promise objects - and even though everybody should know that I don't think we should implicitly change the meaning of @return.

Contributor

cboulanger commented Nov 30, 2017

A lot to be said for each of these solutions, and yet none seems a natural fit. No wonder the JSDoc people haven't come up with a convention yet.

I think I like @return {Promise(Boolean)} best even though the round parentheses kind of suggest similarity to method signature. I think @return {Boolean} is misleading. Async functions return Promise objects - and even though everybody should know that I don't think we should implicitly change the meaning of @return.

@cboulanger

This comment has been minimized.

Show comment
Hide comment
@cboulanger

cboulanger Nov 30, 2017

Contributor

There is a larger story there concerning parameters and return values: should they be describing only the general type of the value, or also its structure (which would be more valuable). It would be a lot more informative to have, for example @return {Promise({ id: String, name: String, age:Number})} than simply @return {Promise} or even @return {Promise(Array)}. BTW, do we use {Map} (for object-based data structures) or only {Object}? But I digress.

Contributor

cboulanger commented Nov 30, 2017

There is a larger story there concerning parameters and return values: should they be describing only the general type of the value, or also its structure (which would be more valuable). It would be a lot more informative to have, for example @return {Promise({ id: String, name: String, age:Number})} than simply @return {Promise} or even @return {Promise(Array)}. BTW, do we use {Map} (for object-based data structures) or only {Object}? But I digress.

@johnspackman

This comment has been minimized.

Show comment
Hide comment
@johnspackman

johnspackman Nov 30, 2017

Member

I don't think we do anything for structures, but JSDoc has a similar pattern:

An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type).

{{a: number, b: string, c}} myObj
// or:
{Object} myObj
{number} myObj.a
{string} myObj.b
{} myObj.c

taken from http://usejsdoc.org/tags-type.html

Member

johnspackman commented Nov 30, 2017

I don't think we do anything for structures, but JSDoc has a similar pattern:

An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type).

{{a: number, b: string, c}} myObj
// or:
{Object} myObj
{number} myObj.a
{string} myObj.b
{} myObj.c

taken from http://usejsdoc.org/tags-type.html

@johnspackman

This comment has been minimized.

Show comment
Hide comment
@johnspackman

johnspackman Nov 30, 2017

Member

closed in error!

Member

johnspackman commented Nov 30, 2017

closed in error!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment