Add support for disabling emit

Resolves #1688.

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
 

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

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

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;

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

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;
 

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,

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

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">) {
     });
     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({

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,26 +211,26 @@ describe("BindOption", () => {
         constructor(public options: Options) {}
 
         @BindOption("emit")
-        emit!: boolean;
+        emit!: EmitStrategy;
     }
 
     it("Supports fetching options", () => {
         const options = new Options(new Logger());
         options.addDefaultDeclarations();
 
         const container = new Container(options);
-        equal(container.emit, false);
+        equal(container.emit, "docs");
     });
 
     it("Updates as option values change", () => {
         const options = new Options(new Logger());
         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");
     });
 });