Support for `as const` enums

[Gerrit0]

Search Terms

as const, enumerations

Problem

Since TypeScript's enum is rather inconvenient to work with, some packages define their own enum-like objects, TypeDoc does this too.

typedoc/src/lib/utils/entry-point.ts

Lines 15 to 35 in 664e27c

	/**
	* Defines how entry points are interpreted.
	* @enum
	*/
	export const EntryPointStrategy = {
	/**
	* The default behavior in v0.22+, expects all provided entry points as being part of a single program.
	* Any directories included in the entry point list will result in `dir/index.[tj]sx?` being used.
	*/
	Resolve: "resolve",
	/**
	* The default behavior in v0.21 and earlier. Behaves like the resolve behavior, but will recursively
	* expand directories into an entry point for each file within the directory.
	*/
	Expand: "expand",
	/**
	* Alternative resolution mode useful for monorepos. With this mode, TypeDoc will look for a package.json
	* and tsconfig.json under each provided entry point. The `main` field of each package will be documented.
	*/
	Packages: "packages",
	} as const;

However, the generated documentation doesn't make it obvious that this value should be treated as an enumeration.

Suggested Solution

Detect variables annotated with @enum with all readonly properties that are string literals, and convert them as an enumeration.

If there is also a type alias by the same name whose content is typeof T[keyof typeof T], remove it from the documentation since enums are also types.

[Gerrit0]

I'm going to look at this again before releasing 0.23, should TypeDoc do this even if you don't tag the variable with @enum?

Vote: 👍 👎

[michkot]

@Gerrit0 Could this be extended for enum-object declarations?

eg. instead of

/** @enum /
export const EntryPointStrategy = {
/*
* abcd
*/
Resolve: "resolve",
} as const;

there is (in .d.ts ) just

/** @enum /
export ( declare ) const EntryPointStrategy: {
/*
* abcd
*/
readonly Resolve: "resolve",
};

there is even a "convenience variant":

/** @enum /
export const EntryPointStrategy: Readonly<{
/*
* abcd
*/
Resolve: "resolve",
}>;

I am happy to open new issue for this if this is doable!
(This is also especially needed when typedoc is executed after pre-processing by api-extractor)

[Gerrit0]

The one without Readonly<> should definitely be possible. The read only one will be more annoying to detect, but probably possible too.