[JS] Ship (synchronous) Iterator Helpers

mdn / content

The content behind MDN Web Docs

https://developer.mozilla.org

Other

9.13k stars 22.45k forks source link

[JS] Ship (synchronous) Iterator Helpers #35698

Open Rumyra opened 2 weeks ago

Rumyra commented 2 weeks ago

Acceptance criteria

[x] The listed features are documented sufficiently on MDN
[x] BCD is updated
[x] Interactive example and data repos are updated if appropriate
[x] The content has been reviewed as needed

For folks helping with Firefox related documentation

[x] Set bugs to dev-doc-complete
[x] Add entry to Firefox release notes for enabled/preview features
[x] Add/remove entry to Firefox experimental features page for preference/released features

Related Gecko bugs

https://bugzilla.mozilla.org/show_bug.cgi?id=1896390

Other

[x] Check content open issues to see if any pertain to the subject matter. If there are any that can be closed because of the work, do so. If there are any that can be fixed relatively quickly because of the knowledge from completing this issue and you have time, feel free to go ahead and fix them.

hamishwillee commented 3 days ago

Status

[x] BCD https://github.com/mdn/browser-compat-data/pull/24332
[x] Docs - look pretty good modulo some inconsistency in intros linking to the iterator helper section on Iterator page - e.g. reduce() is described on that page but not linked from it (while drop() does link. FYI @Josh-Cena
[x] Release notes #35914
[x] dev-docs-complete

Josh-Cena commented 3 days ago

iterator helper section on Iterator page - e.g. reduce() is described on that page but not linked from it (while drop() does link.

Sorry, not sure what you mean? You mean that the drop() page has a link to "Iterator helper"? This is because of the following:

Among these methods, filter(), flatMap(), map(), drop(), and take() return a new Iterator Helper object. The iterator helper is also an Iterator instance, making the helper methods chainable

Only these methods return an "Iterator helper" object. Other methods can be called "Iterator helper" methods, but the term "Iterator helper" itself is not necessary to explain their behavior.

hamishwillee commented 3 days ago

@Josh-Cena Yes, that is what I meant. If you look at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helpers it reads as a topic on "Iterator helpers" not "the iterator helper object". It uses reduce() as the example of what iterator helpers are for.

So my argument here was that this would be a useful link from reduce() and the other iterator helper methods, whether or not they return Iterator helper objects.

I quite like the idea of this topic on the helper rather than helper-object focus because it allows me to understand why they are useful.

Josh-Cena commented 1 day ago

Well I have no opinions about doing that. If you want to mention "iterator helper method" in the description, sure.

hamishwillee commented 1 day ago

Thanks. I think it would be as a See also link from all the methods. But if you're unconvinced, I'm not pushing it.

Josh-Cena commented 1 day ago

Sounds good to me :+1: