Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clearly indicate abstract classes #1874

Closed
ejuda opened this issue Feb 24, 2022 · 1 comment · Fixed by #1914
Closed

Clearly indicate abstract classes #1874

ejuda opened this issue Feb 24, 2022 · 1 comment · Fixed by #1914
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors help wanted Contributions are especially encouraged

Comments

@ejuda
Copy link
Contributor

ejuda commented Feb 24, 2022

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:

    image

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

    image

    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:

    image

  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.
@ejuda ejuda added the enhancement Improved functionality label Feb 24, 2022
@Gerrit0 Gerrit0 added good first issue Easier issue for first time contributors help wanted Contributions are especially encouraged labels Feb 27, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Feb 27, 2022

  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);
    }
  })
}

ejuda added a commit to ejuda/typedoc that referenced this issue Apr 6, 2022
Reflections in TypeDoc can be assigned flags, describing certain
properties of the reflection, e.g. abstract, private, readonly etc.
These flags were rendered using badges for most type of reflections, but
not for reflections which are displayed on their own page (like classes,
interfaces etc.). This made it difficult to establish e.g. whether a
class is abstract (see TypeStrong#1874).

This PR fixes the issue by rendering flags in the page titles next to
the name of the documented entity.

Styling of the badges has been amended, to account for them now showing
next to much bigger headings. The styling was inspired by [Bootstrap
badges](https://getbootstrap.com/docs/4.0/components/badge/).

Partially resolves TypeStrong#1874.
ejuda added a commit to ejuda/typedoc that referenced this issue Apr 7, 2022
Reflections in TypeDoc can be assigned flags, describing certain
properties of the reflection, e.g. abstract, private, readonly etc.
These flags were rendered using badges for most type of reflections, but
not for reflections which are displayed on their own page (like classes,
interfaces etc.). This made it difficult to establish e.g. whether a
class is abstract (see TypeStrong#1874).

This PR fixes the issue by rendering flags in the page titles next to
the name of the documented entity.

Styling of the badges has been amended, to account for them now showing
next to much bigger headings. The styling was inspired by [Bootstrap
badges](https://getbootstrap.com/docs/4.0/components/badge/).

Partially resolves TypeStrong#1874.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors help wanted Contributions are especially encouraged
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants