Not for new code = {{Deprecated_header}}?

MDN
#1

The introduction of Annex B of the ECMA-262 standard says:

… All of the language features and behaviours specified in this annex have one or more undesirable characteristics and in the absence of legacy usage would be removed from this specification. …
… Programmers should not use or assume the existence of these features and behaviours when writing new ECMAScript code. …

This absolutely sounds like “deprecated” to me. However, it doesn’t fit the description text of {{Deprecated_header}}, which states:

… has been removed from the Web standards …
… it is in the process of being dropped …

This doesn’t fit, because introduction of Annex B of the ECMA-262 standard also says:

… However, the usage of these features by large numbers of existing web pages means that web browsers must continue to support them. …

So how should properties defined in Annex B be documented in MDN?

Currently this is handled inconsistently:

MDN-page ECMA‑262 Annex B Tag {{Deprecated
_header}}		 Custom Warning Marked as deprecated in browser compatibility table
escape() B.2.1.1 ✓ ✗ ✓ ✓
unescape() B.2.1.2 ✗ ✗ ✗ ✓
Object.prototype.__proto__ B.2.2.1 ✗ ✗ ✓ ✗
Object.prototype.__defineGetter__() B.2.2.2 ✓ ✗ ✓ ✓
Object.prototype.__defineSetter__() B.2.2.3 ✓ ✗ ✓ ✓
Object.prototype.__lookupGetter__() B.2.2.4 ✓ ✓ ✗ ✓
Object.prototype.__lookupSetter__() B.2.2.5 ✓ ✓ ✗ ✓
String.prototype.substr() B.2.3.1 ✗ ✗ ✗ ✗
String.prototype.anchor() B.2.3.2 ✓ ✓ ✗ ✓
String.prototype.big() B.2.3.3 ✓ ✓ ✗ ✓
String.prototype.blink() B.2.3.4 ✓ ✓ ✗ ✓
String.prototype.bold() B.2.3.5 ✓ ✓ ✗ ✓
String.prototype.fixed() B.2.3.6 ✓ ✓ ✗ ✓
String.prototype.fontcolor() B.2.3.7 ✓ ✓ ✗ ✓
String.prototype.fontsize() B.2.3.8 ✓ ✓ ✗ ✓
String.prototype.italics() B.2.3.9 ✓ ✓ ✗ ✓
String.prototype.link() B.2.3.10 ✓ ✓ ✗ ✓
String.prototype.small() B.2.3.11 ✓ ✓ ✗ ✓
String.prototype.strike() B.2.3.12 ✓ ✓ ✗ ✓
String.prototype.sub() B.2.3.13 ✓ ✓ ✗ ✓
String.prototype.sup() B.2.3.14 ✓ ✓ ✗ ✓
Date.prototype.getYear() B.2.4.1 ✓ ✓ ✗ ✓
Date.prototype.setYear() B.2.4.2 ✓ ✓ ✗ ✓
Date.prototype.toGMTString() B.2.4.3 ✓ ✓ ✗ ✓
RegExp.prototype.compile() B.2.5.1 ✓ ✓ ✗ ✓

Reasons to use {{Deprecated_header}}:

  • Consistent with other pages

Reasons to use a custom deprecation warning:

  • Text fits better
  • Can quote/cite the Introduction text of Annex B to provide evidence, that it is actually deprecated.

The last point actually seems to be important because:

Some MDN-pages, that currently not use {{Deprecated_header}} used {{Deprecated_header}} in older revisions (e.g. escape(), unescape(), String.prototype.substr())

Some MDN-pages, that currently not use the Depricated Tag used it previously (unescape(), Object.prototype.__proto__)

It was removed from these pages with comments like

Regarding the specs, substr is not deprecated nor there is any plan to do so a priori

or

There doesn’t appear to be any evidence (other than circular references on MDN) that this function is deprecated. It’s still in the latest draft and there are no proposals to remove it.

although the same introduction text of annex B existed when the deprecation note was removed. (I believe, that @binoculars, @Ende93 and @SphinxKnight didn’t notice this introduction text when they removed the deprecation notes - and therefore the text should be linked/quoted.)

I think, that this should be handled consistently - but how?

2 Likes
#2

We are sort of in the process of phasing out {{deprecated_header}}. I say “sort of” because the final goal is to have a widget at the top of every page that provides a very simple “this is safe to use on the modern web” type of indication. What form that will take is not decided yet.

It could be just a green/yellow/red system combining the compat details across the board, or it could provide a very quick summary of compatibility with each browser with a row of boxes showing the browser version that added the feature, maybe a color code, and maybe some other basic information.

Brainstorming has happened on that in small bursts the last few months.

Sheppy

#3

Ok, if it is in any case changed soon, I won’t think to much about it and just solve it temporarily:

For all properties defined in ECMA‑262 Annex B …

  • … i’ll add the Deprecated Tag if not already present
  • … i’ll add the custom Warning, that I wrote for escape(), if neither {{Deprecated_header}} nor any other custom “depricated” warning is present

Is that ok?

2 Likes
#4

Makes sense to me. Thank you for all your in-depth work on this!

1 Like
#5

I’ve added the missing tags and headers, although @danm removed the one from String.prototype.substr(…), so I changed it to the custom header from escape(…) and unescape(…).

Now that PR #2469 has been merged, this should no longer happen once 0.0.43 gets published to npm.