[api-documenter] Separate section for classes and errors in package summary

[johanblumenberg-symphony]

trafficstars

Differentiate between regular classes and Error classes in the package summary page.

Since classes and Errors are used for very different purposes, it makes it easier to read the documentation if these two types of classes are separated into different sections. The same thing is done in JavaDoc, exceptions are grouped separately from other classes.

Example code:

export class FooError extends Error { }

export class MyClass {
  /**
   * Do foo
   * 
   * @throws FooError Thrown when there is an error with foo
   */
  foo(): void {

  }
}

Before:

After:

[ghost]

Thank you for your submission, we really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

:x: johanblumenberg-symphony sign now
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[octogonz]

@johanblumenberg-symphony This seems useful, however we might want to consider the design a bit. I can think of a couple edge cases.

For Node.js, you can have multiple levels of inheritance:

class FileError extends Error {
  public readonly filename: string;

  public constructor(filename: string) {
    super()
    this.filename = filename;
  }
}

// This does not extend a class called `Error`, yet it is an error class.
class FileNotFoundError extends FileError { }

For browser applications that target ES5, extending system types doesn't work. There is an awkward workaround (mentioned in that article), but it's awkward enough that many people choose to implement the contract rather than subclassing:

class MyError implements Error {
  public name: string;
  public message: string;

  public constructor(message: string) {
    this.message = message;
    this.name = 'MyError';
   }
}

A couple possible solutions:

1. api-extractor can use type analysis to determine whether something extends or implements Error, and store this information in the .api.json file. That way API Documenter doesn't need to perform this analysis. OR

2. People could manually indicate errors using TSDoc tag. Something like this:

   /**
   * My custom error class
   * @error @public
   */
   export class MyError implements Error {
     public name: string;
     public message: string;
   
     public constructor(message: string) {
       this.message = message;
       this.name = 'MyError';
     }
   }
   

I think my preference might be #2, because it provides more control over the API presentation.

If we go with #1, then we might want an api-documenter.json setting for people who prefer to have their Error objects mixed in with other classes.

What do you think?

[octogonz]

@johanblumenberg-symphony are you able to sign the CLA?