typedoc 0.24.4 → 0.24.6

package/dist/lib/utils/entry-point.js

@@ -68,14 +68,18 @@ exports.EntryPointStrategy = {
 };
 function getEntryPoints(logger, options) {
     const entryPoints = options.getValue("entryPoints");
+    if (entryPoints.length === 0) {
+        logger.error("No entry points were provided.");
+        return;
+    }
     let result;
     const strategy = options.getValue("entryPointStrategy");
     switch (strategy) {
         case exports.EntryPointStrategy.Resolve:
-            result = getEntryPointsForPaths(logger, expandGlobs(entryPoints), options);
+            result = getEntryPointsForPaths(logger, expandGlobs(entryPoints, logger), options);
             break;
         case exports.EntryPointStrategy.Expand:
-            result = getExpandedEntryPointsForPaths(logger, expandGlobs(entryPoints), options);
+            result = getExpandedEntryPointsForPaths(logger, expandGlobs(entryPoints, logger), options);
             break;
         case exports.EntryPointStrategy.LegacyPackages:
             result = getEntryPointsForLegacyPackages(logger, entryPoints, options);
@@ -88,7 +92,7 @@ function getEntryPoints(logger, options) {
             (0, general_1.assertNever)(strategy);
     }
     if (result && result.length === 0) {
-        logger.error("Unable to find any entry points. Make sure TypeDoc can find your tsconfig");
+        logger.error("Unable to find any entry points. See previous warnings.");
         return;
     }
     return result;
@@ -153,7 +157,10 @@ function getEntryPointsForPaths(logger, inputFiles, options, programs = getEntry
                 }
             }
         }
-        logger.warn(`The entry point ${(0, paths_1.nicePath)(fileOrDir)} does not exist or is not included in the program for your provided tsconfig.`);
+        const suggestion = (0, fs_1.isDir)(fileOrDir)
+            ? " If you wanted to include files inside this directory, set --entryPointStrategy to expand or specify a glob."
+            : "";
+        logger.warn(`The entry point ${(0, paths_1.nicePath)(fileOrDir)} is not included in the program for your provided tsconfig.${suggestion}`);
     }
     return entryPoints;
 }
@@ -161,9 +168,23 @@ function getExpandedEntryPointsForPaths(logger, inputFiles, options, programs =
     return getEntryPointsForPaths(logger, expandInputFiles(logger, inputFiles, options), options, programs);
 }
 exports.getExpandedEntryPointsForPaths = getExpandedEntryPointsForPaths;
-function expandGlobs(inputFiles) {
+function expandGlobs(inputFiles, logger) {
     const base = (0, fs_1.deriveRootDir)(inputFiles);
-    const result = inputFiles.flatMap((entry) => (0, fs_1.glob)(entry, base, { includeDirectories: true, followSymlinks: true }));
+    const result = inputFiles.flatMap((entry) => {
+        const result = (0, fs_1.glob)(entry, base, {
+            includeDirectories: true,
+            followSymlinks: true,
+        });
+        if (result.length === 0) {
+            logger.warn(`The entrypoint glob ${(0, paths_1.nicePath)(entry)} did not match any files.`);
+        }
+        else {
+            logger.verbose(`Expanded ${(0, paths_1.nicePath)(entry)} to:\n\t${result
+                .map(paths_1.nicePath)
+                .join("\n\t")}`);
+        }
+        return result;
+    });
     return result;
 }
 function getEntryPrograms(logger, options) {

package/dist/lib/utils/fs.js

@@ -77,7 +77,8 @@ function getCommonDirectory(files) {
         return roots[0].slice(0, -1).join("/");
     }
     let i = 0;
-    while (new Set(roots.map((part) => part[i])).size === 1) {
+    while (i < roots[0].length &&
+        new Set(roots.map((part) => part[i])).size === 1) {
         i++;
     }
     return roots[0].slice(0, i).join("/");

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

@@ -1 +1,2 @@
 export declare function getTextContent(text: string): string;
+export declare function escapeHtml(html: string): string;

package/dist/lib/utils/html.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTextContent = void 0;
+exports.escapeHtml = exports.getTextContent = void 0;
 // There is a fixed list of named character references which will not be expanded in the future.
 // This json file is based on https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references
 // with some modifications to reduce the file size of the original JSON since we just need.
@@ -26,3 +26,14 @@ function getTextContent(text) {
     return unescapeEntities(text.replace(/<.*?(?:>|$)/g, ""));
 }
 exports.getTextContent = getTextContent;
+const htmlEscapes = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+function escapeHtml(html) {
+    return html.replace(/[&<>'"]/g, (c) => htmlEscapes[c]);
+}
+exports.escapeHtml = escapeHtml;

package/dist/lib/utils/jsx.elements.d.ts

@@ -112,8 +112,13 @@ export interface IntrinsicElements {
     video: JsxVideoElementProps;
     wbr: JsxHtmlGlobalProps;
     svg: JsxSvgElementProps;
+    g: JsxGElementProps;
     path: JsxPathElementProps;
     rect: JsxRectElementProps;
+    circle: JsxCircleElementProps;
+    ellipse: JsxEllipseElementProps;
+    polygon: JsxPolygonElementProps;
+    polyline: JsxPolylineElementProps;
     use: JsxUseElementProps;
 }
 export declare const JsxFragment: unique symbol;
@@ -810,6 +815,13 @@ export interface JsxSvgElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, J
     x?: string | number;
     y?: string | number;
 }
+/**
+ * Properties permitted on the `<g>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/g
+ */
+export interface JsxGElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, JsxSvgConditionalProcessingProps, JsxSvgPresentationProps {
+}
 /**
  * Properties permitted on the `<path>` element.
  *
@@ -833,6 +845,46 @@ export interface JsxRectElementProps extends JsxSvgCoreProps, JsxSvgStyleProps,
     x?: string | number;
     y?: string | number;
 }
+/**
+ * Properties permitted on the `<circle>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/circle
+ */
+export interface JsxCircleElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, JsxSvgConditionalProcessingProps, JsxSvgPresentationProps {
+    cx?: string | number;
+    cy?: string | number;
+    r?: string | number;
+    pathLength?: number;
+}
+/**
+ * Properties permitted on the `<ellipse>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/ellipse
+ */
+export interface JsxEllipseElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, JsxSvgConditionalProcessingProps, JsxSvgPresentationProps {
+    cx?: string | number;
+    cy?: string | number;
+    rx?: string | number;
+    ry?: string | number;
+    pathLength?: number;
+}
+/**
+ * Properties permitted on the `<polygon>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/polygon
+ */
+export interface JsxPolygonElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, JsxSvgConditionalProcessingProps, JsxSvgPresentationProps {
+    points?: string;
+    pathLength?: number;
+}
+/** Properties permitted on the `<polyline>` element.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/polyline
+ */
+export interface JsxPolylineElementProps extends JsxSvgCoreProps, JsxSvgStyleProps, JsxSvgConditionalProcessingProps, JsxSvgPresentationProps {
+    points?: string;
+    pathLength?: number;
+}
 /**
  * Properties permitted on the `<use>` element.
  *

package/dist/lib/utils/jsx.js

@@ -15,6 +15,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderElement = exports.createElement = exports.Raw = exports.Fragment = void 0;
+const html_1 = require("./html");
 const jsx_elements_1 = require("./jsx.elements");
 var jsx_elements_2 = require("./jsx.elements");
 Object.defineProperty(exports, "Fragment", { enumerable: true, get: function () { return jsx_elements_2.JsxFragment; } });
@@ -28,16 +29,6 @@ function Raw(_props) {
     return null;
 }
 exports.Raw = Raw;
-const htmlEscapes = {
-    "&": "&",
-    "<": "&lt;",
-    ">": "&gt;",
-    '"': "&quot;",
-    "'": "&#39;",
-};
-function escapeHtml(html) {
-    return html.replace(/[&<>'"]/g, (c) => htmlEscapes[c]);
-}
 const voidElements = new Set([
     "area",
     "base",
@@ -139,7 +130,7 @@ function renderElement(element) {
                 renderChildren(child);
             }
             else if (typeof child === "string" || typeof child === "number") {
-                html.push(escapeHtml(child.toString()));
+                html.push((0, html_1.escapeHtml)(child.toString()));
             }
             else {
                 html.push(renderElement(child));

package/dist/lib/utils/options/declaration.d.ts

@@ -100,6 +100,10 @@ export interface TypeDocOptionMap {
     titleLink: string;
     navigationLinks: ManuallyValidatedOption<Record<string, string>>;
     sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
+    navigation: {
+        includeCategories: boolean;
+        includeGroups: boolean;
+    };
     visibilityFilters: ManuallyValidatedOption<{
         protected?: boolean;
         private?: boolean;
@@ -122,6 +126,7 @@ export interface TypeDocOptionMap {
     categorizeByGroup: boolean;
     defaultCategory: string;
     categoryOrder: string[];
+    groupOrder: string[];
     sort: SortStrategy[];
     kindSortOrder: ReflectionKind.KindString[];
     treatWarningsAsErrors: boolean;
@@ -170,6 +175,16 @@ export type JsDocCompatibility = {
      * On by default, this is how VSCode renders blocks.
      */
     defaultTag: boolean;
+    /**
+     * If set, TypeDoc will warn if a `@inheritDoc` tag is spelled without TSDoc capitalization
+     * (i.e. `@inheritdoc`). On by default.
+     */
+    inheritDocTag: boolean;
+    /**
+     * If set, TypeDoc will not emit warnings about unescaped `{` and `}` characters encountered
+     * when parsing a comment. On by default.
+     */
+    ignoreUnescapedBraces: boolean;
 };
 /**
  * Converts a given TypeDoc option key to the type of the declaration expected.

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

@@ -407,6 +407,71 @@ function addTypeDocOptions(options) {
             }
         },
     });
+    options.addDeclaration({
+        name: "navigation",
+        help: "Determines how the navigation sidebar is organized.",
+        type: declaration_1.ParameterType.Flags,
+        defaults: {
+            includeCategories: false,
+            includeGroups: false,
+        },
+    });
+    options.addDeclaration({
+        name: "visibilityFilters",
+        help: "Specify the default visibility for builtin filters and additional filters according to modifier tags.",
+        type: declaration_1.ParameterType.Mixed,
+        configFileOnly: true,
+        defaultValue: {
+            protected: false,
+            private: false,
+            inherited: true,
+            external: false,
+        },
+        validate(value) {
+            const knownKeys = ["protected", "private", "inherited", "external"];
+            if (!value || typeof value !== "object") {
+                throw new Error("visibilityFilters must be an object.");
+            }
+            for (const [key, val] of Object.entries(value)) {
+                if (!key.startsWith("@") && !knownKeys.includes(key)) {
+                    throw new Error(`visibilityFilters can only include the following non-@ keys: ${knownKeys.join(", ")}`);
+                }
+                if (typeof val !== "boolean") {
+                    throw new Error(`All values of visibilityFilters must be booleans.`);
+                }
+            }
+        },
+    });
+    options.addDeclaration({
+        name: "searchCategoryBoosts",
+        help: "Configure search to give a relevance boost to selected categories",
+        type: declaration_1.ParameterType.Mixed,
+        configFileOnly: true,
+        defaultValue: {},
+        validate(value) {
+            if (!isObject(value)) {
+                throw new Error("The 'searchCategoryBoosts' option must be a non-array object.");
+            }
+            if (Object.values(value).some((x) => typeof x !== "number")) {
+                throw new Error("All values of 'searchCategoryBoosts' must be numbers.");
+            }
+        },
+    });
+    options.addDeclaration({
+        name: "searchGroupBoosts",
+        help: 'Configure search to give a relevance boost to selected kinds (eg "class")',
+        type: declaration_1.ParameterType.Mixed,
+        configFileOnly: true,
+        defaultValue: {},
+        validate(value) {
+            if (!isObject(value)) {
+                throw new Error("The 'searchGroupBoosts' option must be a non-array object.");
+            }
+            if (Object.values(value).some((x) => typeof x !== "number")) {
+                throw new Error("All values of 'searchGroupBoosts' must be numbers.");
+            }
+        },
+    });
     ///////////////////////////
     ///// Comment Options /////
     ///////////////////////////
@@ -417,6 +482,8 @@ function addTypeDocOptions(options) {
         defaults: {
             defaultTag: true,
             exampleTag: true,
+            inheritDocTag: true,
+            ignoreUnescapedBraces: true,
         },
     });
     options.addDeclaration({
@@ -472,7 +539,7 @@ function addTypeDocOptions(options) {
         name: "categorizeByGroup",
         help: "Specify whether categorization will be done at the group level.",
         type: declaration_1.ParameterType.Boolean,
-        defaultValue: true,
+        defaultValue: true, // 0.25, change this to false.
     });
     options.addDeclaration({
         name: "defaultCategory",
@@ -484,6 +551,30 @@ function addTypeDocOptions(options) {
         help: "Specify the order in which categories appear. * indicates the relative order for categories not in the list.",
         type: declaration_1.ParameterType.Array,
     });
+    options.addDeclaration({
+        name: "groupOrder",
+        help: "Specify the order in which groups appear. * indicates the relative order for groups not in the list.",
+        type: declaration_1.ParameterType.Array,
+        // Defaults to the same as the defaultKindSortOrder in sort.ts
+        defaultValue: [
+            kind_1.ReflectionKind.Reference,
+            // project is never a child so never added to a group
+            kind_1.ReflectionKind.Module,
+            kind_1.ReflectionKind.Namespace,
+            kind_1.ReflectionKind.Enum,
+            kind_1.ReflectionKind.EnumMember,
+            kind_1.ReflectionKind.Class,
+            kind_1.ReflectionKind.Interface,
+            kind_1.ReflectionKind.TypeAlias,
+            kind_1.ReflectionKind.Constructor,
+            kind_1.ReflectionKind.Property,
+            kind_1.ReflectionKind.Variable,
+            kind_1.ReflectionKind.Function,
+            kind_1.ReflectionKind.Accessor,
+            kind_1.ReflectionKind.Method,
+            // others are never added to groups
+        ].map(kind_1.ReflectionKind.pluralString),
+    });
     options.addDeclaration({
         name: "sort",
         help: "Specify the sort strategy for documented values.",
@@ -515,62 +606,6 @@ function addTypeDocOptions(options) {
             }
         },
     });
-    options.addDeclaration({
-        name: "visibilityFilters",
-        help: "Specify the default visibility for builtin filters and additional filters according to modifier tags.",
-        type: declaration_1.ParameterType.Mixed,
-        configFileOnly: true,
-        defaultValue: {
-            protected: false,
-            private: false,
-            inherited: true,
-            external: false,
-        },
-        validate(value) {
-            const knownKeys = ["protected", "private", "inherited", "external"];
-            if (!value || typeof value !== "object") {
-                throw new Error("visibilityFilters must be an object.");
-            }
-            for (const [key, val] of Object.entries(value)) {
-                if (!key.startsWith("@") && !knownKeys.includes(key)) {
-                    throw new Error(`visibilityFilters can only include the following non-@ keys: ${knownKeys.join(", ")}`);
-                }
-                if (typeof val !== "boolean") {
-                    throw new Error(`All values of visibilityFilters must be booleans.`);
-                }
-            }
-        },
-    });
-    options.addDeclaration({
-        name: "searchCategoryBoosts",
-        help: "Configure search to give a relevance boost to selected categories",
-        type: declaration_1.ParameterType.Mixed,
-        configFileOnly: true,
-        defaultValue: {},
-        validate(value) {
-            if (!isObject(value)) {
-                throw new Error("The 'searchCategoryBoosts' option must be a non-array object.");
-            }
-            if (Object.values(value).some((x) => typeof x !== "number")) {
-                throw new Error("All values of 'searchCategoryBoosts' must be numbers.");
-            }
-        },
-    });
-    options.addDeclaration({
-        name: "searchGroupBoosts",
-        help: 'Configure search to give a relevance boost to selected kinds (eg "class")',
-        type: declaration_1.ParameterType.Mixed,
-        configFileOnly: true,
-        defaultValue: {},
-        validate(value) {
-            if (!isObject(value)) {
-                throw new Error("The 'searchGroupBoosts' option must be a non-array object.");
-            }
-            if (Object.values(value).some((x) => typeof x !== "number")) {
-                throw new Error("All values of 'searchGroupBoosts' must be numbers.");
-            }
-        },
-    });
     ///////////////////////////
     ///// General Options /////
     ///////////////////////////

package/dist/lib/utils/package-manifest.js

@@ -88,6 +88,12 @@ function expandPackages(logger, packageJsonDir, workspaces, exclude) {
     // as it actually is simpler from an implementation perspective anyway.
     return workspaces.flatMap((workspace) => {
         const globbedPackageJsonPaths = (0, fs_2.glob)((0, path_1.resolve)(packageJsonDir, workspace, "package.json"), (0, path_1.resolve)(packageJsonDir));
+        if (globbedPackageJsonPaths.length === 0) {
+            logger.warn(`The entrypoint glob ${(0, paths_1.nicePath)(workspace)} did not match any directories containing package.json.`);
+        }
+        else {
+            logger.verbose(`Expanded ${(0, paths_1.nicePath)(workspace)} to:\n\t${globbedPackageJsonPaths.map(paths_1.nicePath).join("\n\t")}`);
+        }
         return globbedPackageJsonPaths.flatMap((packageJsonPath) => {
             if ((0, paths_1.matchesAny)(exclude, (0, path_1.dirname)(packageJsonPath))) {
                 return [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "homepage": "https://typedoc.org",
   "exports": {
     ".": "./dist/index.js",