typedoc 0.24.0-beta.1 → 0.24.0-beta.3

package/dist/lib/utils/options/readers/index.d.ts

@@ -1,3 +1,4 @@
 export { ArgumentsReader } from "./arguments";
+export { PackageJsonReader } from "./package-json";
 export { TSConfigReader } from "./tsconfig";
 export { TypeDocReader } from "./typedoc";

package/dist/lib/utils/options/readers/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeDocReader = exports.TSConfigReader = exports.ArgumentsReader = void 0;
+exports.TypeDocReader = exports.TSConfigReader = exports.PackageJsonReader = exports.ArgumentsReader = void 0;
 var arguments_1 = require("./arguments");
 Object.defineProperty(exports, "ArgumentsReader", { enumerable: true, get: function () { return arguments_1.ArgumentsReader; } });
+var package_json_1 = require("./package-json");
+Object.defineProperty(exports, "PackageJsonReader", { enumerable: true, get: function () { return package_json_1.PackageJsonReader; } });
 var tsconfig_1 = require("./tsconfig");
 Object.defineProperty(exports, "TSConfigReader", { enumerable: true, get: function () { return tsconfig_1.TSConfigReader; } });
 var typedoc_1 = require("./typedoc");

package/dist/lib/utils/options/readers/package-json.d.ts

@@ -0,0 +1,9 @@
+import type { OptionsReader } from "..";
+import type { Logger } from "../../loggers";
+import type { Options } from "../options";
+export declare class PackageJsonReader implements OptionsReader {
+    order: number;
+    supportsPackages: boolean;
+    name: string;
+    read(container: Options, logger: Logger, cwd: string): void;
+}

package/dist/lib/utils/options/readers/package-json.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageJsonReader = void 0;
+const assert_1 = require("assert");
+const paths_1 = require("../../paths");
+const fs_1 = require("../../fs");
+const path_1 = require("path");
+class PackageJsonReader {
+    constructor() {
+        // Should run after the TypeDoc config reader but before the TS config
+        // reader, so that it can still specify a path to a `tsconfig.json` file.
+        this.order = 150;
+        this.supportsPackages = true;
+        this.name = "package-json";
+    }
+    read(container, logger, cwd) {
+        const result = (0, fs_1.discoverPackageJson)(cwd);
+        if (!result) {
+            return;
+        }
+        const { file, content } = result;
+        if ("typedoc" in content) {
+            logger.warn(`The 'typedoc' key in ${(0, paths_1.nicePath)(file)} was used by the legacy-packages entryPointStrategy and will be ignored.`);
+        }
+        const optsKey = "typedocOptions";
+        if (!(optsKey in content)) {
+            return;
+        }
+        const opts = content[optsKey];
+        if (opts === null || typeof opts !== "object") {
+            logger.error(`Failed to parse the "typedocOptions" field in ${(0, paths_1.nicePath)(file)}, ensure it exists and contains an object.`);
+            return;
+        }
+        for (const [opt, val] of Object.entries(opts)) {
+            try {
+                container.setValue(opt, val, (0, path_1.dirname)(file));
+            }
+            catch (err) {
+                (0, assert_1.ok)(err instanceof Error);
+                logger.error(err.message);
+            }
+        }
+    }
+}
+exports.PackageJsonReader = PackageJsonReader;

package/dist/lib/utils/options/readers/tsconfig.js

@@ -1,31 +1,11 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TSConfigReader = void 0;
 const path_1 = require("path");
-const ts = __importStar(require("typescript"));
+const typescript_1 = __importDefault(require("typescript"));
 const fs_1 = require("../../fs");
 const assert_1 = require("assert");
 const validation_1 = require("../../validation");
@@ -162,7 +142,7 @@ class TSConfigReader {
             return;
         }
         this.seenTsdocPaths.add(path);
-        const { config, error } = ts.readConfigFile((0, fs_1.normalizePath)(path), ts.sys.readFile);
+        const { config, error } = typescript_1.default.readConfigFile((0, fs_1.normalizePath)(path), typescript_1.default.sys.readFile);
         if (error) {
             logger.error(`Failed to read tsdoc.json file at ${(0, paths_1.nicePath)(path)}.`);
             return;

package/dist/lib/utils/options/readers/typedoc.d.ts

@@ -24,7 +24,7 @@ export declare class TypeDocReader implements OptionsReader {
      */
     private readFile;
     /**
-     * Search for the typedoc.js or typedoc.json file from the given path
+     * Search for the configuration file given path
      *
      * @param  path Path to the typedoc.(js|json) file. If path is a directory
      *   typedoc file will be attempted to be found at the root of this path

package/dist/lib/utils/options/readers/typedoc.js

@@ -22,11 +22,14 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypeDocReader = void 0;
 const path_1 = require("path");
 const FS = __importStar(require("fs"));
-const ts = __importStar(require("typescript"));
+const typescript_1 = __importDefault(require("typescript"));
 const assert_1 = require("assert");
 const paths_1 = require("../../paths");
 const fs_1 = require("../../fs");
@@ -73,7 +76,7 @@ class TypeDocReader {
         seen.add(file);
         let fileContent;
         if (file.endsWith(".json")) {
-            const readResult = ts.readConfigFile((0, fs_1.normalizePath)(file), (path) => FS.readFileSync(path, "utf-8"));
+            const readResult = typescript_1.default.readConfigFile((0, fs_1.normalizePath)(file), (path) => FS.readFileSync(path, "utf-8"));
             if (readResult.error) {
                 logger.error(`Failed to parse ${(0, paths_1.nicePath)(file)}, ensure it exists and contains an object.`);
                 return;
@@ -120,7 +123,7 @@ class TypeDocReader {
         }
     }
     /**
-     * Search for the typedoc.js or typedoc.json file from the given path
+     * Search for the configuration file given path
      *
      * @param  path Path to the typedoc.(js|json) file. If path is a directory
      *   typedoc file will be attempted to be found at the root of this path
@@ -132,9 +135,17 @@ class TypeDocReader {
         return [
             path,
             (0, path_1.join)(path, "typedoc.json"),
+            (0, path_1.join)(path, "typedoc.jsonc"),
+            (0, path_1.join)(path, "typedoc.config.js"),
+            (0, path_1.join)(path, "typedoc.config.cjs"),
             (0, path_1.join)(path, "typedoc.js"),
-            (0, path_1.join)(path, ".config/typedoc.js"),
+            (0, path_1.join)(path, "typedoc.cjs"),
             (0, path_1.join)(path, ".config/typedoc.json"),
+            (0, path_1.join)(path, ".config/typedoc.jsonc"),
+            (0, path_1.join)(path, ".config/typedoc.config.js"),
+            (0, path_1.join)(path, ".config/typedoc.config.cjs"),
+            (0, path_1.join)(path, ".config/typedoc.js"),
+            (0, path_1.join)(path, ".config/typedoc.cjs"),
         ].find(fs_1.isFile);
     }
 }

package/dist/lib/utils/options/sources/typedoc.js

@@ -99,6 +99,51 @@ function addTypeDocOptions(options) {
         help: "Prevent symbols that are not explicitly documented from appearing in the results.",
         type: declaration_1.ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "excludeNotDocumentedKinds",
+        help: "Specify the type of reflections that can be removed by excludeNotDocumented.",
+        type: declaration_1.ParameterType.Array,
+        validate(value) {
+            const invalid = new Set(value);
+            const valid = new Set((0, enum_1.getEnumKeys)(kind_1.ReflectionKind));
+            for (const notPermitted of [
+                kind_1.ReflectionKind.Project,
+                kind_1.ReflectionKind.TypeLiteral,
+                kind_1.ReflectionKind.TypeParameter,
+                kind_1.ReflectionKind.Parameter,
+                kind_1.ReflectionKind.ObjectLiteral,
+            ]) {
+                valid.delete(kind_1.ReflectionKind[notPermitted]);
+            }
+            for (const v of valid) {
+                invalid.delete(v);
+            }
+            if (invalid.size !== 0) {
+                throw new Error(`excludeNotDocumentedKinds may only specify known values, and invalid values were provided (${Array.from(invalid).join(", ")}). The valid kinds are:\n${Array.from(valid).join(", ")}`);
+            }
+        },
+        defaultValue: [
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Module],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Namespace],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Enum],
+            // Not including enum member here by default
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Variable],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Function],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Class],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Interface],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Constructor],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Property],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Method],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.CallSignature],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.IndexSignature],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.ConstructorSignature],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Accessor],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.GetSignature],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.SetSignature],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.TypeAlias],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Reference],
+        ],
+    });
     options.addDeclaration({
         name: "excludeInternal",
         help: "Prevent symbols that are marked with @internal from being documented.",
@@ -156,6 +201,7 @@ function addTypeDocOptions(options) {
         help: "Specify the location the documentation should be written to.",
         type: declaration_1.ParameterType.Path,
         hint: declaration_1.ParameterHint.Directory,
+        defaultValue: "./docs",
     });
     options.addDeclaration({
         name: "json",
@@ -558,16 +604,16 @@ function addTypeDocOptions(options) {
             }
         },
         defaultValue: [
-            "Enum",
-            "EnumMember",
-            "Variable",
-            "Function",
-            "Class",
-            "Interface",
-            "Property",
-            "Method",
-            "Accessor",
-            "TypeAlias",
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Enum],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.EnumMember],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Variable],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Function],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Class],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Interface],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Property],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Method],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.Accessor],
+            kind_1.ReflectionKind[kind_1.ReflectionKind.TypeAlias],
         ],
     });
     options.addDeclaration({

package/dist/lib/utils/sort.d.ts

@@ -5,5 +5,5 @@
 import type { DeclarationReflection } from "../models/reflections/declaration";
 import type { Options } from "./options";
 export declare const SORT_STRATEGIES: readonly ["source-order", "alphabetical", "enum-value-ascending", "enum-value-descending", "static-first", "instance-first", "visibility", "required-first", "kind"];
-export type SortStrategy = typeof SORT_STRATEGIES[number];
+export type SortStrategy = (typeof SORT_STRATEGIES)[number];
 export declare function getSortFunction(opts: Options): (reflections: DeclarationReflection[]) => void;

package/dist/lib/validation/documentation.js

@@ -23,11 +23,23 @@ function validateDocumentation(project, logger, requiredToBeDocumented) {
     }
     const toProcess = project.getReflectionsByKind(kinds);
     const seen = new Set();
-    while (toProcess.length) {
+    outer: while (toProcess.length) {
         const ref = toProcess.shift();
         if (seen.has(ref))
             continue;
         seen.add(ref);
+        // If there is a parameter inside another parameter, this is probably a callback function.
+        // TypeDoc doesn't support adding comments with @param to nested parameters, so it seems
+        // silly to warn about these.
+        if (ref.kindOf(models_1.ReflectionKind.Parameter)) {
+            let r = ref.parent;
+            while (r) {
+                if (r.kindOf(models_1.ReflectionKind.Parameter)) {
+                    continue outer;
+                }
+                r = r.parent;
+            }
+        }
         if (ref instanceof models_1.DeclarationReflection) {
             const signatures = ref.type instanceof models_1.ReflectionType
                 ? ref.type.declaration.getNonIndexSignatures()

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.24.0-beta.1",
+  "version": "0.24.0-beta.3",
   "homepage": "https://typedoc.org",
   "exports": {
     ".": "./dist/index.js",
-    "./tsdoc.json": "./tsdoc.json"
+    "./tsdoc.json": "./tsdoc.json",
+    "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
   "bin": {
@@ -24,9 +25,9 @@
   },
   "dependencies": {
     "lunr": "^2.3.9",
-    "marked": "^4.2.4",
-    "minimatch": "^5.1.1",
-    "shiki": "^0.11.1"
+    "marked": "^4.2.12",
+    "minimatch": "^7.1.3",
+    "shiki": "^0.14.1"
   },
   "peerDependencies": {
     "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x"
@@ -34,20 +35,19 @@
   "devDependencies": {
     "@types/lunr": "^2.3.4",
     "@types/marked": "^4.0.8",
-    "@types/minimatch": "5.1.2",
-    "@types/mocha": "^9.1.1",
+    "@types/mocha": "^10.0.1",
     "@types/node": "14",
-    "@typescript-eslint/eslint-plugin": "^5.46.1",
-    "@typescript-eslint/parser": "^5.46.1",
+    "@typescript-eslint/eslint-plugin": "^5.51.0",
+    "@typescript-eslint/parser": "^5.51.0",
     "@typestrong/fs-fixture-builder": "github:TypeStrong/fs-fixture-builder#8abd1494280116ff5318dde2c50ad01e1663790c",
     "c8": "^7.12.0",
-    "esbuild": "^0.16.8",
-    "eslint": "^8.30.0",
+    "esbuild": "^0.17.7",
+    "eslint": "^8.34.0",
     "mocha": "^10.2.0",
-    "prettier": "2.8.1",
+    "prettier": "2.8.4",
     "puppeteer": "^13.5.2",
     "ts-node": "^10.9.1",
-    "typescript": "4.9.4"
+    "typescript": "4.9.5"
   },
   "files": [
     "/bin",
@@ -61,11 +61,11 @@
     "/tsdoc.json"
   ],
   "scripts": {
-    "test": "mocha -r ts-node/register --config .config/mocha.fast.json",
-    "test:cov": "c8 mocha -r ts-node/register --config .config/mocha.fast.json",
+    "test": "mocha --config .config/mocha.fast.json",
+    "test:cov": "c8 mocha --config .config/mocha.fast.json",
     "doc:c": "node bin/typedoc --tsconfig src/test/converter/tsconfig.json",
     "doc:c2": "node bin/typedoc --tsconfig src/test/converter2/tsconfig.json",
-    "test:full": "c8 mocha -r ts-node/register --config .config/mocha.full.json",
+    "test:full": "c8 mocha --config .config/mocha.full.json",
     "test:visual": "ts-node ./src/test/capture-screenshots.ts && ./scripts/compare_screenshots.sh",
     "test:visual:accept": "node scripts/accept_visual_regression.js",
     "rebuild_specs": "node scripts/rebuild_specs.js",