jquery / jquery/api.jquery.com

promise method of promise object currently not documented

Open
#375 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted
Dominant language
HTML
Stars
325
Forks
260
PR merge metrics
No merged PRs in 30d

Description

jaubourg states at http://bugs.jquery.com/ticket/14293#comment:2:

As for determining if an object is a promise... you test for the presence of a method called promise and call it to get the actual promise

The presence of the .promise method on the promise object is currently not documented.

It is missing in two places. One place is http://api.jquery.com/deferred.promise which currently states:

The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, and state),...

The list of methods should include the promise method (and should not include the deprecated pipe method) and thus should be:

The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, progress, state and promise),...

It would also be very helpful if http://api.jquery.com/deferred.promise documents the fact that one can/should determine if an object is a promise by testing for the presence of the promise method, as jaubourg described. For example:

To test if an object is a promise, you test for the presence of a method called promise.

Another place is http://api.jquery.com/Types/#Promise which currently states:

This object provides a subset of the methods of the Deferred object (then, done, fail, always, pipe. isResolved, and isRejected) to...

The list of methods should include the promise method. Additionally, the list currently includes deprecated methods. Instead, it should say:

This object provides a subset of the methods of the Deferred object (then, done, fail, always, progress, state and promise) to...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Update the deferred.promise and Types/#Promise documentation pages. Start by locating those two pages and compare their method lists with the requested wording: include promise and progress, remove deprecated pipe, isResolved, and isRejected references, and document checking for a promise method. Done means both pages accurately describe the current Promise API.

Written by the indexing model from the issue text.

Assessment

Tech stack
jquery
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.