Clearly indicate abstract classes

[ejuda]

Search Terms

abstract, class, constructor

Problems

Consider the following class:

export abstract class SomeClass {
    abstract abstractProp: boolean;
    abstract abstractMethod(): void;
}

1. While TypeDoc does indicate which methods and properties are abstract:

   

   it does not provide any indication on whether the class itself is abstract:

   

   This means that the users cannot easily establish whether the class they are looking at is abstract - they have to rely on abstract methods and properties being present.

2. Secondly, even if a constructor of an abstract class may be not explictly defined (as in the example above), TypeDoc will still add the constructor to the documentation page. While this is useful for concrete classes (indicating the class has a default constructor), it is potentially misleading for abstract classes, as they cannot be instantiated directly.

Suggested Solutions

1. It would be easier to spot abstract classes if the _Abstract_ badge was present prominently near the class name, for example in the header:

   

2. If the constructor of an abstract class has not been explicitly defined, TypeDoc should not add an empty constructor, to further emphasise that the class cannot be instantiated directly. If the constructor has been defined, it should be preserved, as it might e.g. be accompanied by a docstring.

[Gerrit0]

1. Is definitely a good idea, and something we should do.
2. I think is better suited for a plugin. Constructors and their parameters are still useful to know about if the user is inheriting from this class.

const td = require("typedoc");

/** @param {td.Application} */
exports.load = function(app) {
  app.converter.on(td.Converter.EVENT_RESOLVE, (context, reflection) => {
    if (reflection.kindOf(td.ReflectionKind.Class) && reflection.flags.isAbstract) {
       const ctor = reflection.getChildByName("constructor")
      // could check reflection.sources to see if it is associated with any user written code
      if (ctor) context.project.removeReflection(ctor);
    }
  })
}