Grammatical ambiguity in .then() return value description

[OP-TechTrekker]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then

What specific section or headline is this issue about?

Return value

What information was incorrect, unhelpful, or incomplete?

"Returns a new Promise immediately. This new promise is always pending when returned, regardless of the current promise's status.

One of the onFulfilled and onRejected handlers will be executed to handle the current promise's fulfillment or rejection. The call always happens asynchronously, even when the current promise is already settled. The behavior of the returned promise (call it p) depends on the handler's execution result, following a specific set of rules. If the handler function:

returns a value: p gets fulfilled with the returned value as its value.
doesn't return anything: p gets fulfilled with undefined as its value.
throws an error: p gets rejected with the thrown error as its value.
returns an already fulfilled promise: p gets fulfilled with that promise's value as its value.
returns an already rejected promise: p gets rejected with that promise's value as its value.
returns another pending promise: p is pending and becomes fulfilled/rejected with that promise's value as its value immediately after that promise becomes fulfilled/rejected."

In the second paragraph the phrase "the returned promise (call it p)" can be grammatically ambigious. As its a noun phrase, it can either mean 'p' is returned by .then() pointing back to the only returned promise in the previous context as antecedent or it can imply the handlers have returned a promise 'p' where its acts as noun to introduce the promise returned by the handler. And both are grammatically valid, which can create ambiguity.
In the later case where 'p' can grammatically mean the promise returned by handler, the sentence will be read as "The behavior of the returned promise (call it p) by handler depends on the handler's execution result, following a specific set of rules". It can be a circular sentence but its still grammatically valid , as behaviour of promise by handler can be a term and the handler execution result i.e a promise now can be another term.

Also the terms used can be inconsistent, as the promise returned by .then() is said to be "new promise" repeatedly, and the promise is on which .then() is attached is termed as "current promise".
The introduction of term "returned promise" without it being specified can create confusion and ambiguity.

What did you expect to see?

It would be better to specify directly to whom the returned promise 'p' belongs to, instead of needing to imply what it belongs to.

Do you have any supporting links, references, or citations?

(9a771cd)
In above link it can be seen from and onwards line 54, it was directly specified that behaviour of promise returned by .then() is depend upon the handler execution result. Its easier to understand and direct.

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/javascript/reference/global_objects/promise/then
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/javascript/reference/global_objects/promise/then/index.md
• Last commit: 544b843
• Document last modified: 2025-07-10T09:07:55.000Z