1210827 - Finalised and approved methods of the Promise API in ECMAScript 2015 are marked as experimental in the docs

Status: RESOLVED FIXED

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

Description

[Behrang]

:: Developer Documentation Request

      Request Type: Correction
     Gecko Version: unspecified
 Technical Contact: 

:: Details

According to http://www.ecma-international.org/ecma-262/6.0/#sec-promise-constructor, Promise.all, Promise.race, Promise.reject, etc. are all finalised and in the spec.

However on https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise, they have the experimental icon shown next to them.

There's this note on the page, but its message is not very clear:

> [1] Gecko 24 has an experimental implementation of Promise, under the initial name of Future. It was renamed to its final name in Gecko 25, but disabled by default behind the flag dom.promise.enabled. Bug 918806 enabled Promises by default in Gecko 29.

Does "experimental" mean that the implementation is not ready for production use and potentially buggy or that the API is experimental? If it means the former, I think rather than "experimental", a better name should be used (e.g. "work in progress" or "implementation not complete"). Alternatively the tooltip should clarify the meaning a bit further.

IMHO using the word "experimental" for approved and finalised APIs in the spec is a little bit confusing.

Please see the the screenshot for more information: http://i.imgur.com/2lvBPi0.png

Comment 1

[Behrang]

Attachment: Screen Shot 2015-10-03 at 1.13.54 AM.png

Comment 2

[Florian Scholz (Open Web Docs)]

Yep, we need to remove the green banners and the "experimental" tag, so that these icons will disappear from ES2015 feature pages. This will likely happen soon along with other mass-updates.

Comment 3

[Behrang]

Hi Florian,

It would be nice if there was a "legend" at, for example, the bottom of every page that explained what each icon means (experimental, deprecated, obsolete, not-standardized, etc.) even though most of them are self-explanatory. I actually I think only "experimental" is a little bit ambiguous. I think it can be split into more categories:

* Standardized but not fully implemented
* Standardized but implementation is not stable/ready for production use
* Proposed for standardization but still a draft
* etc.

Comment 4

[Florian Scholz (Open Web Docs)]

I have removed the experimental icons and banners from Promise pages.

(In reply to Behrang from comment #3)
> I actually I think only "experimental" is a little bit
> ambiguous. I think it can be split into more categories:
> 
> * Standardized but not fully implemented
> * Standardized but implementation is not stable/ready for production use
> * Proposed for standardization but still a draft
> * etc.

I think the spec tables that we have already indicate stability in terms of standardization and so do the compat tables in terms of engine support. You have to read those two things and decide if this is enough stability for your current project. Depends on the readers environment and is unlikely a decision we can make.

How we use "Experimental" is really ambiguous at the moment. I think for us it would make sense to use "Experimental" only if: 

a) the feature is indeed experimental and needs to be activated with a preference / feature flag.
b) the feature is only available in Nightly or Canary channels.

Comment 5

[Florian Scholz (Open Web Docs)]

Pages on the Promise API have been fixed. Also added the new ES 2016 spec to the spec table.

Other pages are getting this gradually too. I think we are done here; if there is a need to discuss other improvements, always feel free to email the mailing list https://groups.google.com/forum/#!forum/mozilla.dev.mdc

Comment 6

[Eric Shepherd [:sheppy]]

(In reply to Behrang from comment #3)
> Hi Florian,
> 
> It would be nice if there was a "legend" at, for example, the bottom of
> every page that explained what each icon means (experimental, deprecated,
> obsolete, not-standardized, etc.) even though most of them are
> self-explanatory. I actually I think only "experimental" is a little bit
> ambiguous. I think it can be split into more categories:
> 
> * Standardized but not fully implemented
> * Standardized but implementation is not stable/ready for production use
> * Proposed for standardization but still a draft
> * etc.

FWIW, if you point at the icons, you get a little explanation of what they mean. But I agree with the broader point that we need to clarify what these mean, perhaps.

Comment 7

[Behrang]

> FWIW, if you point at the icons, you get a little explanation of what they mean. But I agree with the broader point that we need to clarify what these mean, perhaps.

Hi Eric,

I was aware of that. But, IIRC, I hovered over the icon for Promise.all and the tooltip was "Experimental". Yet the feature was a part of the finalized ECMAScript 2015 spec and I got confused: has someone forgotten to remove the icon? Does it mean the implementation is not ready for production use?