diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a2252549..2d9858f1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,14 @@ "intentionallyNotExported": ["src/foo.ts:Foo"] } ``` +- The `--emit` option can now be used to more finely control what TypeDoc will emit. + | Value | Behavior | + | --- | --- | + | `both` | Emit both documentation and JS. | + | `docs` | Emit documentation, but not JS (default). | + | `none` | Emit nothing, just convert and run validation. | + | `true` | Alias for `both`, for backwards compatibility. Will be removed in 0.23. | + | `false` | Alias for `docs`, for backwards compatibility. Will be removed in 0.23. | ### Bug Fixes diff --git a/bin/typedoc b/bin/typedoc index a03ea74ac..81745b55c 100755 --- a/bin/typedoc +++ b/bin/typedoc @@ -105,27 +105,30 @@ async function run(app) { return ExitCodes.ValidationError; } - const out = app.options.getValue("out"); - if (out) { - await app.generateDocs(project, out); - } - const json = app.options.getValue("json"); - if (json) { - await app.generateJson(project, json); - } - - if (!out && !json) { - await app.generateDocs(project, "./docs"); + if (app.options.getValue("emit") !== "none") { + const out = app.options.getValue("out"); + if (out) { + await app.generateDocs(project, out); + } + const json = app.options.getValue("json"); + if (json) { + await app.generateJson(project, json); + } + + if (!out && !json) { + await app.generateDocs(project, "./docs"); + } + + if (app.logger.hasErrors()) { + return ExitCodes.OutputError; + } + if ( + app.options.getValue("treatWarningsAsErrors") && + app.logger.hasWarnings() + ) { + return ExitCodes.OutputError; + } } - if (app.logger.hasErrors()) { - return ExitCodes.OutputError; - } - if ( - app.options.getValue("treatWarningsAsErrors") && - app.logger.hasWarnings() - ) { - return ExitCodes.OutputError; - } return ExitCodes.Ok; } diff --git a/src/lib/application.ts b/src/lib/application.ts index 23240ec30..1d3770012 100644 --- a/src/lib/application.ts +++ b/src/lib/application.ts @@ -223,7 +223,10 @@ export class Application extends ChildableComponent< return; } - if (this.options.getValue("emit")) { + if ( + this.options.getValue("emit") === "both" || + this.options.getValue("emit") === true + ) { for (const program of programs) { program.emit(); } diff --git a/src/lib/converter/context.ts b/src/lib/converter/context.ts index cb533d396..63a90f498 100644 --- a/src/lib/converter/context.ts +++ b/src/lib/converter/context.ts @@ -77,7 +77,7 @@ export class Context { * /** We should use this comment */ * export * as Mod from "./mod" * ``` - * Will be removed in 0.22. + * Will be removed in 0.23. * @internal */ exportSymbol?: ts.Symbol; diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts index fc20f87a7..5652f9fc8 100644 --- a/src/lib/converter/plugins/CommentPlugin.ts +++ b/src/lib/converter/plugins/CommentPlugin.ts @@ -207,7 +207,7 @@ export class CommentPlugin extends ConverterComponent { if (!specialOverloadCase) return; } - // Clean this up in 0.22. We should really accept a ts.Symbol so we don't need exportSymbol on Context + // Clean this up in 0.23. We should really accept a ts.Symbol so we don't need exportSymbol on Context const exportNode = context.exportSymbol?.getDeclarations()?.[0]; let rawComment = exportNode && getRawComment(exportNode, this.application.logger); diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts index 0ed608984..5b600cba9 100644 --- a/src/lib/utils/options/declaration.ts +++ b/src/lib/utils/options/declaration.ts @@ -4,6 +4,16 @@ import type { SortStrategy } from "../sort"; import { isAbsolute, join, resolve } from "path"; import type { EntryPointStrategy } from "../entry-point"; +export const EmitStrategy = { + true: true, // Alias for both, for backwards compatibility until 0.23 + false: false, // Alias for docs, for backwards compatibility until 0.23 + both: "both", // Emit both documentation and JS + docs: "docs", // Emit documentation, but not JS (default) + none: "none", // Emit nothing, just convert and run validation +} as const; +/** @hidden */ +export type EmitStrategy = typeof EmitStrategy[keyof typeof EmitStrategy]; + /** * An interface describing all TypeDoc specific options. Generated from a * map which contains more information about each option for better types when @@ -61,7 +71,7 @@ export interface TypeDocOptionMap { includes: string; media: string; - emit: boolean; + emit: typeof EmitStrategy; watch: boolean; preserveWatchOutput: boolean; diff --git a/src/lib/utils/options/index.ts b/src/lib/utils/options/index.ts index a38842db3..4583415df 100644 --- a/src/lib/utils/options/index.ts +++ b/src/lib/utils/options/index.ts @@ -1,7 +1,7 @@ export { Options, BindOption } from "./options"; export type { OptionsReader } from "./options"; export { ArgumentsReader, TypeDocReader, TSConfigReader } from "./readers"; -export { ParameterType, ParameterHint } from "./declaration"; +export { EmitStrategy, ParameterType, ParameterHint } from "./declaration"; export type { TypeDocOptions, diff --git a/src/lib/utils/options/options.ts b/src/lib/utils/options/options.ts index 720cd4be9..08103a2c7 100644 --- a/src/lib/utils/options/options.ts +++ b/src/lib/utils/options/options.ts @@ -328,7 +328,10 @@ export class Options { ): ts.CompilerOptions { const result = { ...options }; - if (!this.getValue("emit")) { + if ( + this.getValue("emit") !== "both" && + this.getValue("emit") !== true + ) { result.noEmit = true; delete result.emitDeclarationOnly; } diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts index 682fbd9e9..8d9ebd79d 100644 --- a/src/lib/utils/options/sources/typedoc.ts +++ b/src/lib/utils/options/sources/typedoc.ts @@ -1,6 +1,6 @@ import type { Options } from ".."; import { LogLevel } from "../../loggers"; -import { ParameterType, ParameterHint } from "../declaration"; +import { ParameterType, ParameterHint, EmitStrategy } from "../declaration"; import { BUNDLED_THEMES, Theme } from "shiki"; import { SORT_STRATEGIES } from "../../sort"; import { EntryPointStrategy } from "../../entry-point"; @@ -99,8 +99,10 @@ export function addTypeDocOptions(options: Pick) { }); options.addDeclaration({ name: "emit", - help: "If set, TypeDoc will emit the TypeScript compilation result", - type: ParameterType.Boolean, + help: "Specify what TypeDoc should emit, 'docs', 'both', or 'none'.", + type: ParameterType.Map, + map: EmitStrategy, + defaultValue: "docs", }); options.addDeclaration({ diff --git a/src/test/utils/options/options.test.ts b/src/test/utils/options/options.test.ts index 542ba5fef..e7c34b7ca 100644 --- a/src/test/utils/options/options.test.ts +++ b/src/test/utils/options/options.test.ts @@ -5,7 +5,10 @@ import { NumberDeclarationOption, } from "../../../lib/utils/options"; import { deepStrictEqual as equal, throws } from "assert"; -import type { DeclarationOption } from "../../../lib/utils/options"; +import type { + DeclarationOption, + EmitStrategy, +} from "../../../lib/utils/options"; describe("Options", () => { const logger = new Logger(); @@ -208,7 +211,7 @@ describe("BindOption", () => { constructor(public options: Options) {} @BindOption("emit") - emit!: boolean; + emit!: EmitStrategy; } it("Supports fetching options", () => { @@ -216,7 +219,7 @@ describe("BindOption", () => { options.addDefaultDeclarations(); const container = new Container(options); - equal(container.emit, false); + equal(container.emit, "docs"); }); it("Updates as option values change", () => { @@ -224,10 +227,10 @@ describe("BindOption", () => { options.addDefaultDeclarations(); const container = new Container(options); - equal(container.emit, false); + equal(container.emit, "docs"); - options.setValue("emit", true); - equal(container.emit, true); + options.setValue("emit", "both"); + equal(container.emit, "both"); }); it("Caches set options when frozen", () => { @@ -236,12 +239,12 @@ describe("BindOption", () => { const container = new Container(options); - options.setValue("emit", true); + options.setValue("emit", "both"); options.freeze(); - equal(container.emit, true); + equal(container.emit, "both"); const prop = Object.getOwnPropertyDescriptor(container, "emit")!; equal(prop.get, void 0); - equal(prop.value, true); + equal(prop.value, "both"); }); });