Consider joining TypedArrays, Errors, and other classes with many subclasses

[ghost]

I consider these two pages to be exemplary cases of what I would like to suggest redoing:

• /docs/Web/JavaScript/Reference/Global_Objects/TypedArray
• /docs/Web/JavaScript/Reference/Global_Objects/Error

They have one thing in common: they both have a lot of subclasses that no nothing different, or very little different, from their bases.

Currently, keeping their subclass' pages in sync with each other seems error-prone and tedious, because they should be near exactly the same, save for the name of the subclass used in place of the original, and specialized examples (particularly for the TypedArrays).

For example, I was about to add the error cases for the TypedArray constructor. There are about 4 or 5 error causes, 2 of which are located at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#examples. Now, I was going to add them to each subclass' constructor page, under parameters in an "Exceptions" section... but if the errors are all the same, why should this be duplicated? The parameters are already duplicated, but these two errors in #examples already gives us a mismatch between how most other pages are handled.

Could something be done to improve these cases?

There are 11 TypedArray constructors, and 11 Error subclasses. Of these subclasses, the only one to have any real divergence from the general behaviour would be AggregateError, for which I would say that it deserves its own page.

[hamishwillee]

FWIW my understanding is that TypedArray is not a subclass in the spec, though it may be under the hood used as such. It's a convenient name to reference a whole bunch of things that just happen to have the same kinds of behaviours.

You make a good point that there is a lot of duplication. IFF we can verify that all the included types should always have exactly the same description then we could link from each of the sub-array types to the parent.

[ghost]

FWIW my understanding is that TypedArray is not a subclass in the spec, though it may be under the hood used as such.

I am not quite sure what you mean? Neither TypedArray nor Error are subclasses, the situation is that these are the base classes upon which others subclass, e.g. Reflect.getPrototypeOf(Uint8Array) === %TypedArray%.

See https://tc39.es/ecma262/multipage/indexed-collections.html#sec-%typedarray%-intrinsic-object,

is a constructor function object that all of the TypedArray constructor objects inherit from.

It's a convenient name to reference a whole bunch of things that just happen to have the same kinds of behaviours.

This is precisely how I suggest MDN document these two. Again, taking the above specification reference as an example, we don't need whole pages per each, but rather a small table of differences should suffice.

[hamishwillee]

We used to use a macro to include documentation that was assumed to be a 1:1 match from one place to another. This was removed recently because very often there would be minor differences the change in the "original" would make the included cases incorrect, often in subtle or non-obvious ways.

As part of the removal much of the text was duplicated rather than included - the assumption being that the cost of maintenance is worth the duplication.
In other cases a "master" copy was created and linked to from the duplications. The theory being that at least since the "master" is separate it is obvious that there might be many affected parts.

Upshot, I'm not at all opposed to the suggestion of removing the duplication IF we know that they are all going to be exactly the same.

IF they might have subtle differences then we need to make sure that we manage this in such a way that finding the differences is easy. Otherwise duplication may actually be a long term better way to do this, despite the cost.

Do you know of any subtle differences that we would need to record now?

@wbamberg May have some comments.

[ghost]

Do you know of any subtle differences that we would need to record now?

For the Error subclasses, the only differences are the circumstances under which they are thrown, that 7 of them are global, 3 are within the WebAssembly namespace, and that InternalError isn't standard. They all behave exactly the same, just with different names. Then there's AggregateError, which has a different constructor, is defined differently, and has an object property that the others don't. I wouldn't consider these subtle, but it might not warrant the current level of repetition?

[teoli2003]

This is worth discussing, but I don't think we should act on this too early. This has so many implications (for maintenance, for authors, for readers, …) that we should be careful.

Also, we have so many moving parts that I think we should wait a bit (read: end of the year, maybe? Surely not in Q3 2022): it is difficult to cope with all the fundamental discussions and updates of MDN.

Let's finish some of the Demix events, the page type, the JS modernization, the ESLint/Prettier automation (and there are several more!) projects before moving to this. We still have some dictionaries to remove, to finish fixing sidebars and header banners, …

Sorry to slow this down, but we need to avoid starting everything and finishing nothing 😃 MDN was born 17 years ago and will still be there in a few months: we have tackled so many problems/opportunities since its inception.

[hamishwillee]

Sure. I'd like @wbamberg comments before anything on this one too.

[teoli2003]

I also would like @Elchi3 insights here.

[Elchi3]

I have previously shared my thoughts about how to document inheritance (or subclasses) here: https://github.com/mdn/content/discussions/5798. We haven't decided on a way forward yet.