API structure conventions: inheritance

[schalkneethling]

Discussed in https://github.com/orgs/mdn/discussions/205

^{Originally posted by Elchi3 January 6, 2021}
We probably discussed this already somewhere but I'm opening a new issue here.
(I'm also thinking about mix-ins but I figured it might be easier to make a call on simple inheritance structures first.)

I'm picking a random API that has inheritance. It is DOM Range.

interface AbstractRange
interface Range : AbstractRange
interface StaticRange : AbstractRange

So, here we have two constructible classes Range() and StaticRange() and we have a class called AbstractRange which both inherit from.

MDN documents AbstractRange here:

• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/collapsed
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/endContainer
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/endOffset
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/startContainer
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/startOffset

MDN documents Range here:

• https://developer.mozilla.org/en-US/docs/Web/API/Range
• https://developer.mozilla.org/en-US/docs/Web/API/Range/setStart (and many more Range-specific members)

MDN documents StaticRange here:

• https://developer.mozilla.org/en-US/docs/Web/API/StaticRange

Now, MDN documents Range.collapsed and StaticRange.collapsed along with AbstractRange.collapse:

• https://developer.mozilla.org/en-US/docs/Web/API/Range/collapsed
• https://developer.mozilla.org/en-US/docs/Web/API/StaticRange/collapsed
• https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange/collapsed

(and this is true for all AbstractRange members, you find them all also under Range and StaticRange).

Observations:

• There are 3 documents describing the same thing basically.
• The 3 documents could be describe the 3 different things way better actually (with their specific compat data, or specific code example etc), but this isn't really happening.
• Only the Range variant manages to provide a code example. StaticRange could have a code example and for AbstractRange you would probably need to refer to Range and StaticRange for practical code.
• The compat data for AbstractRange is weird and doesn't make sense to me as is.

So, what is the convention here? I think there are options:

1. Document all abstract and concrete classes plus all their members (seems like this is what is done currently)
2. Only create an abstract class main page and omit abstract members pages. Document all concrete classes with pages for all members.
3. Document abstract class and plus all abstract member pages. Only document concrete classes with their specific members and refer to abstract members instead of creating additional pages for them.

[Rumyra]

@Elchi3 we're moving discussions out of mdn/content - I believe this discussion was resolved, can you confirm? If which case we can keep the discussion locked & archived - thanks!

[Elchi3]

I don't think this is resolved yet.
The link above to the original discussion is a 404. It is here: mdn/mdn-community#205 (and has more content than what is in this issue).

I also referred to this discussion from another recent issue but I guess the moving around of things breaks those links, too.

[Rumyra]

Thanks @Elchi3 - can we unlock and unarchive the discussion @schalkneethling

As far as the broken links go I think that's something for github

[Rumyra]

Discussion unlocked and unarchived 👍 mdn/mdn-community#205