JS docs: Have constructor pages instead of prototype pages

[bershanskiy]

In #2537 @wbamberg and @Elchi3 proposed to completely separate object constructors (that are callable with new keyword) from the objects they construct. This is a meta issue to track which pages still need to be separated and updated.

Update (by @Elchi3): This was actually discussed in London at the stumptown work week. The JS docs should follow the API docs and have pages for constructors instead of pages for prototypes. The prototype pages are mostly useless (and introduce weird usage of the page macro). Having pages for constructors instead seems more useful and consistent with API docs.

An update to BCD is also needed, see e.g. mdn/browser-compat-data#5440.

Pages (might not be complete)

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/InternalError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet

[Elchi3]

Thanks for filing this issue @bershanskiy! I've updated the description a bit here to give more context.

[Elchi3]

Hey @SphinxKnight, just a heads-up that this is happening. Some restructuring in the JS docs, see above. I hope it won't be too much of a hassle for locales.

[SphinxKnight]

@Elchi3 Thanks a lot :) I've seen it coming, I don't think it is too painful and I (personnally) appreciate the distinction between constructors and types. Thanks again (and happy 2020 :))

[Elchi3]

The BCD updates are merged and should be on the site this Thursday.

I'm going to leave a comment here with the list of pages again, but this time only listing those that I've refactored already and that are ready for review. Please tick the box if you've reviewed it and/or leave your feedback :-)

• Array
• ArrayBuffer
• AsyncFunction (prototype page removed; it adds no real benefit)
• BigInt
• Boolean
• DataView
• Date
• Error
• GeneratorFunction (prototype page removed; it adds no real benefit)
• Map
• Number
• Object
• Promise
• RegExp
• Set
• SharedArrayBuffer
• String
• TypedArray (prototype page removed; constructors are the individual typed array types)
• WeakMap
• WeakSet

The following error type pages had prototype pages but no further sub pages. Instead they are referring to the pages of the main Error object. I've now merged the prototype page with the main page of these, but did not create constructor pages. I guess either we create sub pages for all things (methods, properties, constructors) or no sub pages at all. Let me know if you agree that dealing with this is out of scope for the moment, or not. (TypedArray types have the same thing, don't duplicate the whole API, which is quite large, under each type but instead refer to the generic TypedArray pages. An alternative organization would be that Float32Array lives in the TypedArray tree and is presented as one of many constructors. Same for Error and Error classes maybe.)

• EvalError
• InternalError
• RangeError
• ReferenceError
• SyntaxError
• TypeError
• URIError

[ExE-Boss]

Don’t forget about:

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator

[sideshowbarker]

Since some mdn_url values added in mdn/browser-compat-data#5471 are for MDN articles that don’t exist yet, though the following were added to BCD, they are 404 at this point:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/Object
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/Set
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/Symbol
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/WeakMap
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet/WeakSet

[Elchi3]

Thanks @sideshowbarker, that's because I haven't finished this task yet as it was quite difficult to focus on work last week. I hope I will finish this thing this week and then the 404s should be gone.

[wbamberg]

The compat table at https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility lists "Promise() constructor" but it's not linked. I don't understand why. The data looks all right: https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Promise.json#L55-L58.

[wbamberg]

The opening para of https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer looks like it needs to be updated to be talking about the constructor rather than the object. It goes:

The SharedArrayBuffer object is used to represent...

...where I would have expected something like:

The SharedArrayBuffer() constructor is used to create...

[wbamberg]

The other "Object" pages, like Map, say, get an H2 "Constructor" linking to the constructor page.

But the page for Object doesn't, and still has H2 sections called things like "Properties of the Object constructor".

Is this an intentional difference?

[wbamberg]

The following error type pages had prototype pages but no further sub pages. Instead they are referring to the pages of the main Error object. I've now merged the prototype page with the main page of these, but did not create constructor pages.

A motivation for this issue is to be clear which sorts of objects different pages describe: in particular to split pages that describe objects and pages that describe constructors.

So from this perspective, one question seems to be: what sorts of things do pages like ReferenceError describe?

They seem to describe ReferenceError objects, and are structured with H2 sections called "Methods" and "Properties" (following this pattern: https://github.com/mdn/stumptown-content/blob/master/recipes/javascript-class.yaml). But they also have an H2 "Syntax" section, which is more appropriate for pages that describe constructors and methods (cf. https://github.com/mdn/stumptown-content/blob/master/recipes/javascript-constructor.yaml)

So that makes it look like it is worth having separate, new, "constructor" pages for these Error subtypes, and these page should get the "Syntax" H2 from the existing pages.

I guess either we create sub pages for all things (methods, properties, constructors) or no sub pages at all.

I don't think we need subpages for all the methods and properties. For one thing, from the structured content point of view it's fine for docs to be incomplete. For another, most of them seem to be just derived from the base Error, and so the links at, say, https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError#Methods point to the corresponding page under Error which seems like a reasonable thing to do.

Anyway. That's just my opinion, and maybe I misunderstand it :).

[wbamberg]

@Elchi3 , I looked through all the pages referenced under #2571 (comment), checking things like BCD, whether "object" pages have a "Constructor" H2, whether the content looks sensible and whether the links work properly, and it generally looks great. I made a few comments above.

[sideshowbarker]

FYI, today I created new constructor pages for Intl.PluralRules & Intl.RelativeTimeFormat.

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/PluralRules
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/RelativeTimeFormat

I hope I got it right, as far as the separation between those pages and the pages for their objects.

I’m happy to help with getting new constructor separated out for other objects. I just did these two today because they are two specific ones that I’ve run into some particular annoyances with.

[Elchi3]

The compat table at https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility lists "Promise() constructor" but it's not linked. I don't understand why. The data looks all right: https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Promise.json#L55-L58.

I've noticed this too earlier this week and corrected it in a follow-up PR that made it into yesterday's BCD release, but apparently that release was not pushed prod yet.

The opening para of https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer looks like it needs to be updated to be talking about the constructor rather than the object

Thanks, corrected.

But the page for Object doesn't, and still has H2 sections called things like "Properties of the Object constructor".
Is this an intentional difference?

No, just oversight from my part. I think once we start linting content against recipes we will have to pay attention to sections more carefully.

A motivation for this issue is to be clear which sorts of objects different pages describe: in particular to split pages that describe objects and pages that describe constructors.

Yes, thanks for elaborating this some more. I think you are right in fact. I will look into creating constructor pages for error objects. It makes sense when looking at this from the content type perspective.

[Elchi3]

@wbamberg thank you very much for your review! I've done some corrections and also finished String.

Remaining are the error constructors and WebAssembly and Intl.

For WebAssembly and Intl we have "namespaces" and there is a proposed reorg of this content (#2537). I think "namespace" might be a new content type and the reorg should probably be split out from the constructor work. So, I think, I will go ahead like @sideshowbarker did with PluralRules and RelativeTimeFormat and then we need to talk about how to reorg this with namespaces in mind (a new task in a new sprint).

[Elchi3]

Also, I just realized, if we create constructor pages for the error objects, we would also need to create constructor pages for typed arrays. So make https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array about the object and have a separate page for the constructor there as well.

[wbamberg]

The compat table at https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Browser_compatibility lists "Promise() constructor" but it's not linked. I don't understand why. The data looks all right: https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Promise.json#L55-L58.

I've noticed this too earlier this week and corrected it in a follow-up PR that made it into yesterday's BCD release, but apparently that release was not pushed prod yet.

The opening para of https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer looks like it needs to be updated to be talking about the constructor rather than the object

Thanks, corrected.

But the page for Object doesn't, and still has H2 sections called things like "Properties of the Object constructor".
Is this an intentional difference?

No, just oversight from my part. I think once we start linting content against recipes we will have to pay attention to sections more carefully.

Thanks @Elchi3 , I've verified that these three points are fixed, and checked off the corresponding items in #2571 (comment) 👍

[Elchi3]

Another thing before I forget this: Some compat data is about the constructor but currently lives under the object. See, e.g.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#Browser_compatibility
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set#Browser_compatibility
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#Browser_compatibility
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView#Browser_compatibility
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer#Browser_compatibility

It should be moved.

[bershanskiy]

Other constructor data that might be moved:

• WeakSet
• WeakMap
• All the *Array constructors, obviously.

[Elchi3]

To do list for remaining constructor work:

TypedArrays:

• BCD
• Int8Array
• Uint8Array
• Uint8ClampedArray
• Int16Array
• Uint16Array
• Int32Array
• Uint32Array
• Float32Array
• Float64Array
• BigInt64Array
• BigUint64Array

Errors:

• EvalError
• InternalError
• RangeError
• ReferenceError
• SyntaxError
• TypeError
• URIError

WebAssembly:

• WebAssembly.Global
• WebAssembly.Module
• WebAssembly.Instance
• WebAssembly.Memory
• WebAssembly.Table
• WebAssembly.CompileError
• WebAssembly.LinkError
• WebAssembly.RuntimeError

Intl:

• BCD
• Collator
• DateTimeFormat
• ListFormat
• Locale
• NumberFormat
• PluralRules
• RelativeTimeFormat

[Elchi3]

This took longer than I thought, but I think it is all done now.
(if not, we will probably notice when we match recipes and pages in the stumptown linter soon).