Skip to content

API structure conventions: inheritance #1006

@Elchi3

Description

@Elchi3

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:

MDN documents Range here:

MDN documents StaticRange here:

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

(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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions