Add tag @ignoreNotDocumented to explicitly exclude it from generated docs

[ibc]

Search Terms

"tags", "exclude", "ignore"

Problem

This is pseudo-code since real code is way more complex but I hope I can simplify it:

I have some types for a custom EnhancedEventEmitter class. Basically I have a FooEvents that is the list of events (and their arguments) emitted by class Foo. And this is how it looks once documented by Typedoc:

FooEvents:
    | EventType<"started">
    | EventType<"stopped", [reason: string]>;

Here, EventType is internally defined as this:

export type EventType<Name extends string, Args extends any[] = []> = {
  name: Name;
  args: Args;
};

The application should basically do this:

foo.on('started', () => { ... });
foo.on('stopped', (reason) => { ... });

That's basically all. I don't need that the application has access and documentation about EventType. The application is never gonna need it. So I don't want to pollute the Typedoc generated documentation with the EventType definition. It's perfectly fine that in the FooEvents type generated by Typedoc, EventType is not clickable (which is how it would be if treatWarningsAsErrors is false).

However I want to use treatWarningsAsErrors: true to not miss anything (for example during GitHub CI check actions on PRs).

Suggested Solution

Basically a new tag:

/**
 * @hidden
 * @ignoreNotDocumented
 */
export type EventType<Name extends string, Args extends any[] = []> = {
  name: Name;
  args: Args;
};

Meaning that such a tag is that Typedoc won't complain if it should generate documentation for this type but it doesn't have documentation (due to the @hidden tag). Instead, Typedoc should silently ignore this problem and just print this type in the generated documentation as plain text (instead of a link) and should not include EventType in the generated docs.

Another easier solution would be a @excludeFromDocumentation tag. But this is not the same as @ignore or @hidden. Its meaning would be something like "exclude this type from the generated documentation and do NOT complain if some other type (included in the generated documentation) depends on it".

[Gerrit0]

TypeDoc has the intentionallyNotExported option for this, though at the moment I'm leaning towards thinking that @hidden / @ignore should implicitly add their symbols to that list...

[ibc]

TypeDoc has the intentionallyNotExported option for this, though at the moment I'm leaning towards thinking that @hidden / @ignore should implicitly add their symbols to that list...

Having to write symbols in intentionallyNotExported array is not comfortable at all honestly. And yes, my expectation was that if I add @hidden or @ignore in a type then Typedoc should not complain and should just silently exclude that symbol from the generated doc no matter there are other exported and documented types that depend on it.