-
Notifications
You must be signed in to change notification settings - Fork 23.1k
Description
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 : AbstractRangeSo, 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:
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
Rangevariant manages to provide a code example.StaticRangecould have a code example and forAbstractRangeyou would probably need to refer toRangeandStaticRangefor practical code. - The compat data for
AbstractRangeis weird and doesn't make sense to me as is.
So, what is the convention here? I think there are options:
- Document all abstract and concrete classes plus all their members (seems like this is what is done currently)
- Only create an abstract class main page and omit abstract members pages. Document all concrete classes with pages for all members.
- 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.