typedoc 0.24.0-beta.8 → 0.24.0

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,17 +127,47 @@ 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();

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

@@ -102,6 +102,7 @@ export interface TypeDocOptionMap {
     titleLink: string;
     navigationLinks: ManuallyValidatedOption<Record<string, string>>;
     sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
+    jsDocCompatibility: JsDocCompatibility;
     commentStyle: typeof CommentStyle;
     useTsLinkResolution: boolean;
     blockTags: `@${string}`[];
@@ -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.0",
   "homepage": "https://typedoc.org",
   "exports": {
     ".": "./dist/index.js",