typedoc 0.24.0-beta.8 → 0.24.1

package/dist/lib/converter/comments/index.d.ts

@@ -1,11 +1,12 @@
 import ts from "typescript";
 import { Comment, ReflectionKind } from "../../models";
 import { Logger } from "../../utils";
-import type { CommentStyle } from "../../utils/options/declaration";
+import type { CommentStyle, JsDocCompatibility } from "../../utils/options/declaration";
 export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
     modifierTags: Set<string>;
+    jsDocCompatibility: JsDocCompatibility;
 }
 export declare function clearCommentCache(): void;
 export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;

package/dist/lib/converter/comments/parser.js

@@ -127,24 +127,54 @@ function blockTag(comment, lexer, config, warning) {
     (0, assert_1.ok)(blockTag.kind === lexer_1.TokenSyntaxKind.Tag, "blockTag called not at the start of a block tag."); // blockContent is broken if this fails.
     const tagName = aliasedTags.get(blockTag.text) || blockTag.text;
     let content;
-    if (tagName === "@example") {
+    if (tagName === "@example" && config.jsDocCompatibility.exampleTag) {
         content = exampleBlockContent(comment, lexer, config, warning);
     }
+    else if (tagName === "@default" && config.jsDocCompatibility.defaultTag) {
+        content = defaultBlockContent(comment, lexer, config, warning);
+    }
     else {
         content = blockContent(comment, lexer, config, warning);
     }
     return new models_1.CommentTag(tagName, content);
 }
+/**
+ * The `@default` tag gets a special case because otherwise we will produce many warnings
+ * about unescaped/mismatched/missing braces in legacy JSDoc comments
+ */
+function defaultBlockContent(comment, lexer, config, warning) {
+    lexer.mark();
+    const content = blockContent(comment, lexer, config, () => { });
+    const end = lexer.done() || lexer.peek();
+    lexer.release();
+    if (content.some((part) => part.kind === "code")) {
+        return blockContent(comment, lexer, config, warning);
+    }
+    const tokens = [];
+    while ((lexer.done() || lexer.peek()) !== end) {
+        tokens.push(lexer.take());
+    }
+    const blockText = tokens
+        .map((tok) => tok.text)
+        .join("")
+        .trim();
+    return [
+        {
+            kind: "code",
+            text: makeCodeBlock(blockText),
+        },
+    ];
+}
 /**
  * The `@example` tag gets a special case because otherwise we will produce many warnings
- * about unescaped/mismatched/missing braces
+ * about unescaped/mismatched/missing braces in legacy JSDoc comments.
  */
 function exampleBlockContent(comment, lexer, config, warning) {
     lexer.mark();
     const content = blockContent(comment, lexer, config, () => { });
     const end = lexer.done() || lexer.peek();
     lexer.release();
-    if (content.some((part) => part.kind === "code")) {
+    if (content.some((part) => part.kind === "code" && part.text.startsWith("```"))) {
         return blockContent(comment, lexer, config, warning);
     }
     const tokens = [];

package/dist/lib/converter/converter.js

@@ -72,6 +72,7 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
         this.compile(entryPoints, context);
         this.resolve(context);
         this.trigger(Converter_1.EVENT_END, context);
+        this._config = undefined;
         return project;
     }
     /** @internal */
@@ -238,6 +239,7 @@ let Converter = Converter_1 = class Converter extends component_1.ChildableCompo
             blockTags: new Set(this.application.options.getValue("blockTags")),
             inlineTags: new Set(this.application.options.getValue("inlineTags")),
             modifierTags: new Set(this.application.options.getValue("modifierTags")),
+            jsDocCompatibility: this.application.options.getValue("jsDocCompatibility"),
         };
         return this._config;
     }

package/dist/lib/converter/types.js

@@ -392,8 +392,8 @@ const queryConverter = {
         }
         return new models_1.QueryType(models_1.ReferenceType.createSymbolReference(context.resolveAliasedSymbol(querySymbol), context, node.exprName.getText()));
     },
-    convertType(context, type) {
-        const symbol = type.getSymbol();
+    convertType(context, type, node) {
+        const symbol = type.getSymbol() || context.getSymbolAtLocation(node.exprName);
         (0, assert_1.default)(symbol, `Query type failed to get a symbol for: ${context.checker.typeToString(type)}. This is a bug.`);
         return new models_1.QueryType(models_1.ReferenceType.createSymbolReference(context.resolveAliasedSymbol(symbol), context));
     },

package/dist/lib/output/themes/default/partials/anchor-icon.d.ts

@@ -1,3 +1,3 @@
 import { JSX } from "../../../../utils";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
-export declare const anchorIcon: (context: DefaultThemeRenderContext, anchor: string | undefined) => JSX.Element;
+export declare function anchorIcon(context: DefaultThemeRenderContext, anchor: string | undefined): JSX.Element;

package/dist/lib/output/themes/default/partials/anchor-icon.js

@@ -2,5 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.anchorIcon = void 0;
 const utils_1 = require("../../../../utils");
-const anchorIcon = (context, anchor) => (utils_1.JSX.createElement("a", { href: `#${anchor}`, "aria-label": "Permalink", class: "tsd-anchor-icon" }, context.icons.anchor()));
+function anchorIcon(context, anchor) {
+    if (!anchor)
+        return utils_1.JSX.createElement(utils_1.JSX.Fragment, null);
+    return (utils_1.JSX.createElement("a", { href: `#${anchor}`, "aria-label": "Permalink", class: "tsd-anchor-icon" }, context.icons.anchor()));
+}
 exports.anchorIcon = anchorIcon;

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

@@ -59,6 +59,7 @@ export interface TypeDocOptionMap {
     options: string;
     tsconfig: string;
     compilerOptions: unknown;
+    plugin: string[];
     entryPoints: string[];
     entryPointStrategy: typeof EntryPointStrategy;
     exclude: string[];
@@ -70,9 +71,13 @@ export interface TypeDocOptionMap {
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeReferences: boolean;
-    externalSymbolLinkMappings: ManuallyValidatedOption<Record<string, Record<string, string>>>;
-    media: string;
-    includes: string;
+    name: string;
+    includeVersion: boolean;
+    disableSources: boolean;
+    sourceLinkTemplate: string;
+    gitRevision: string;
+    gitRemote: string;
+    readme: string;
     out: string;
     json: string;
     pretty: boolean;
@@ -82,58 +87,54 @@ export interface TypeDocOptionMap {
     darkHighlightTheme: ShikiTheme;
     customCss: string;
     markedOptions: unknown;
-    name: string;
-    includeVersion: boolean;
-    disableSources: boolean;
     basePath: string;
-    excludeTags: `@${string}`[];
-    readme: string;
     cname: string;
-    sourceLinkTemplate: string;
-    gitRevision: string;
-    gitRemote: string;
     htmlLang: string;
     githubPages: boolean;
+    cacheBust: boolean;
     gaID: string;
     hideGenerator: boolean;
-    cacheBust: boolean;
     searchInComments: boolean;
     cleanOutputDir: boolean;
     titleLink: string;
     navigationLinks: ManuallyValidatedOption<Record<string, string>>;
     sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
+    visibilityFilters: ManuallyValidatedOption<{
+        protected?: boolean;
+        private?: boolean;
+        inherited?: boolean;
+        external?: boolean;
+        [tag: `@${string}`]: boolean;
+    }>;
+    searchCategoryBoosts: ManuallyValidatedOption<Record<string, number>>;
+    searchGroupBoosts: ManuallyValidatedOption<Record<string, number>>;
     commentStyle: typeof CommentStyle;
     useTsLinkResolution: boolean;
+    jsDocCompatibility: JsDocCompatibility;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];
     modifierTags: `@${string}`[];
+    excludeTags: `@${string}`[];
+    externalSymbolLinkMappings: ManuallyValidatedOption<Record<string, Record<string, string>>>;
+    media: string;
+    includes: string;
     categorizeByGroup: boolean;
     defaultCategory: string;
     categoryOrder: string[];
     sort: SortStrategy[];
     kindSortOrder: ReflectionKind.KindString[];
-    visibilityFilters: ManuallyValidatedOption<{
-        protected?: boolean;
-        private?: boolean;
-        inherited?: boolean;
-        external?: boolean;
-        [tag: `@${string}`]: boolean;
-    }>;
-    searchCategoryBoosts: ManuallyValidatedOption<Record<string, number>>;
-    searchGroupBoosts: ManuallyValidatedOption<Record<string, number>>;
+    treatWarningsAsErrors: boolean;
+    treatValidationWarningsAsErrors: boolean;
+    intentionallyNotExported: string[];
+    validation: ValidationOptions;
+    requiredToBeDocumented: ReflectionKind.KindString[];
     watch: boolean;
     preserveWatchOutput: boolean;
-    skipErrorChecking: boolean;
     help: boolean;
     version: boolean;
     showConfig: boolean;
-    plugin: string[];
     logLevel: typeof LogLevel;
-    treatWarningsAsErrors: boolean;
-    treatValidationWarningsAsErrors: boolean;
-    intentionallyNotExported: string[];
-    validation: ValidationOptions;
-    requiredToBeDocumented: ReflectionKind.KindString[];
+    skipErrorChecking: boolean;
 }
 /**
  * Wrapper type for values in TypeDocOptionMap which are represented with an unknown option type, but
@@ -157,6 +158,18 @@ export type ValidationOptions = {
      */
     notDocumented: boolean;
 };
+export type JsDocCompatibility = {
+    /**
+     * If set, TypeDoc will treat `@example` blocks as code unless they contain a code block.
+     * On by default, this is how VSCode renders blocks.
+     */
+    exampleTag: boolean;
+    /**
+     * If set, TypeDoc will treat `@default` blocks as code unless they contain a code block.
+     * On by default, this is how VSCode renders blocks.
+     */
+    defaultTag: boolean;
+};
 /**
  * Converts a given TypeDoc option key to the type of the declaration expected.
  */

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

@@ -67,7 +67,7 @@ class Options {
     snapshot() {
         const key = {};
         optionSnapshots.set(key, {
-            values: { ...this._values },
+            values: JSON.stringify(this._values),
             set: new Set(this._setOptions),
         });
         return key;
@@ -78,7 +78,7 @@ class Options {
      */
     restore(snapshot) {
         const data = optionSnapshots.get(snapshot);
-        this._values = { ...data.values };
+        this._values = JSON.parse(data.values);
         this._setOptions = new Set(data.set);
     }
     /**

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

@@ -404,6 +404,15 @@ function addTypeDocOptions(options) {
     ///////////////////////////
     ///// Comment Options /////
     ///////////////////////////
+    options.addDeclaration({
+        name: "jsDocCompatibility",
+        help: "Sets compatibility options for comment parsing that increase similarity with JSDoc comments.",
+        type: declaration_1.ParameterType.Flags,
+        defaults: {
+            defaultTag: true,
+            exampleTag: true,
+        },
+    });
     options.addDeclaration({
         name: "commentStyle",
         help: "Determines how TypeDoc searches for comments.",

package/package.json

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

package/static/style.css

@@ -228,6 +228,8 @@ dd {
 
 .container-main {
     margin: 0 auto;
+    /* toolbar, footer, margin */
+    min-height: calc(100vh - 41px - 56px - 4rem);
 }
 
 @keyframes fade-in {