1109166 - Coherent docs for JS generators and iterators (ES6 and legacy)

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: JavaScript, defect, P5)

Description

[Florian Scholz (Open Web Docs)]

:: Developer Documentation Request

      Request Type: New Documentation
     Gecko Version: unspecified
 Technical Contact: 

:: Details

Reference articles for new ES6 generators and iterators are mostly written. The guide needs to have a chapter about them, too.
Also, we need to outline that people shouldn't use any legacy generators/iterators anymore. (MDN has not much material on those and we also lack reference pages for them).

Steps (for everyone who wants to help):

* Make a list of all ES6 reference pages for iterators/generators, complete them and post them here.
* Do the same for legacy iterators/generators, make sure these pages are all marked as deprecated.
* Write/update the chapter in the guide

Comment 1

[Tooru Fujisawa [:arai]]

Currently following documents exist.
Some of them are overlapped, and some of them are missing content or page.

Reference Documents for ES6 generator:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function*
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield*
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction/prototype

Guide documents for ES6 generator (they are overlapped):
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/iterable

Reference documents for Legacy generator:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator
  (StopIteration linked from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects but not exist)

Guide documents for Legacy generator:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators


Constructor of legacy generator is Function. so no need for writing new page.

Comment 2

[Tooru Fujisawa [:arai]]

note that some of above links are corrupted (trailing "*" is dropped)...

"The_Iterator_protocol" page contains the section for legacy iterator protocol.
It would be better to merge ES6 iterator(iterable) protocol into single page,
also, add dedicated page for legacy iterator protocol.

Comment 3

[Tooru Fujisawa [:arai]]

Updated following documents:

Reference documents for Legacy generator:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/Legacy_generator_function
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Legacy_generator_function
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/StopIteration

Guide documents for Legacy generator:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/The_legacy_Iterator_protocol

Also, merged https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/iterable into https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol .

still need some more brush up.

Comment 4

[Florian Scholz (Open Web Docs)]

Thank you very much. This is great! \o/

I will review these docs soon and I already reviewed some of them.

More notes:

There is a chapter about functions which should mention that besides normal functions, generator functions also exist: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions

Also, analog to array comprehensions, we need to create a page for generator comprehensions.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Array_comprehensions
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Generator_comprehensions
(also requested in bug 1060430)

Comment 5

[Florian Scholz (Open Web Docs)]

In addition to all the docs mentioned in the previous comments, I also removed legacy iterators and generators from the guide now and added es6 code to it. For historical reasons when can mention legacy things on the reference pages, but a guide and tutorials to JS should be talking about what actually matters and is standardized.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators

Closing as we are waaay better than before now. There is always room to improve the docs, though! :)