An unclear sentence about promises

[lkintact]

MDN URL

https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises

What specific section or headline is this issue about?

Chaining promises

What information was incorrect, unhelpful, or incomplete?

Hi,
There's a phrase in the article:

"But the elegant feature of promises is that then() itself returns a promise, which will be completed with the result of the function passed to it".

Sorry if I'm simply being dumb, but for me, as a beginner in promises, that sounds unclear, and raises questions:

1. What does it mean that a promise will be "completed" with the result of the function? Perhaps "settled" is meant?
2. What is the "result" of the function? Perhaps "return value" is meant?
3. To what ("to it") will the "result" be passed, then() or the promise?

What did you expect to see?

A sentence understandable by people the article is intended for.

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

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/learn_web_development/extensions/async_js/promises
• MDN URL: https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/learn_web_development/extensions/async_js/promises/index.md
• Last commit: 48d220a
• Document last modified: 2025-04-11T19:13:37.000Z

[chrisdavidmills]

I think you are right that the sentence is confusing. The terminology being used here is correct, to my knowledge, but it uses new terms without explaining them. We could really do with fixing this.

To answer your questions:

1. AFAIK, "completed" and "settled" basically mean the same thing — this is when the promise leaves its pending state (meaning it is waiting for a result) and either fulfills (runs the success callback inside the following .then() block), or rejects (the failure case, this is what .catch() is used to handle later in the article).
2. Yes, result and return value mean the same thing, at least in this context.
3. It is the .then(). The callback function is passed into the .then() call as an argument.

I think we need to rewrite this sentence to clarify these points (with quick definitions provided in parentheses), and also update the Promise terminology section to do a better job of explaining all the terminology (e.g., why doesn't it cover "completed").

I hope the above helps. Do you have any further thoughts on what is needed here?

[Josh-Cena]

You can refer to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#description for authoritative definitions of these terms. I, too, would consider "completed" and "settled" as synonymous.

[amritamishra01]

Hi @lkintact 👋, I’m participating in Hacktoberfest 2025, and I’d love to work on improving this section to make the explanation clearer for beginners.

I can rewrite the sentence with simpler phrasing (using terms like “settled” and “return value”) and also add a short clarification note in the Promise terminology section for better understanding.

Please assign this issue to me if that’s okay. Thank you!

[chrisdavidmills]

Hi there, @amritamishra01; thank you for your interest in working on this issue. I've assigned it to you, and I'm happy to review your PR once you've submitted it.

Please take note of what I've said in my earlier comment. Clarify the sentence. I think "result (return value)" would be good to use, as "result" is often used in the scope of promises, but the reader will be more familiar with "return value".

I'd favor "completed" over "settled", as I think it sounds more intuitive and action-oriented. But I'll leave it up to you. You could say something like "completed (moves out of a pending state to a success or failure state)".

Just make sure all the terminology is explained in the terminology section and consistent throughout the article.

[lkintact]

I hope the above helps. Do you have any further thoughts on what is needed here?

@chrisdavidmills Thank you, it did help. I've been reading more MDN info, and maybe a link to the more complete explanation of what then() returns should be added to the article?