typedoc 0.23.0-beta.6 → 0.23.1

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from "./lib/models";
 export { Converter, Context, type CommentParserConfig } from "./lib/converter";
 export { Renderer, DefaultTheme, DefaultThemeRenderContext, UrlMapping, Theme, PageEvent, RendererEvent, MarkdownEvent, } from "./lib/output";
 export type { RenderTemplate, RendererHooks } from "./lib/output";
-export { ArgumentsReader, BindOption, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, } from "./lib/utils";
+export { ArgumentsReader, BindOption, CommentStyle, JSX, LogLevel, Logger, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, EntryPointStrategy, EventHooks, } from "./lib/utils";
 export type { OptionsReader, TypeDocOptions, TypeDocOptionMap, ValidationOptions, TypeDocOptionValues, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, SortStrategy, ParameterTypeToOptionTypeMap, DocumentationEntryPoint, ManuallyValidatedOption, } from "./lib/utils";
 export type { EventMap, EventCallback } from "./lib/utils/events";
 export { JSONOutput, Serializer, type SerializerComponent, SerializeEvent, } from "./lib/serialization";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScript = exports.SerializeEvent = exports.Serializer = exports.JSONOutput = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.BindOption = exports.ArgumentsReader = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.normalizePath = exports.resetReflectionID = exports.Event = exports.EventDispatcher = exports.Application = void 0;
+exports.TypeScript = exports.SerializeEvent = exports.Serializer = exports.JSONOutput = exports.EventHooks = exports.EntryPointStrategy = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.Logger = exports.LogLevel = exports.JSX = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.MarkdownEvent = exports.RendererEvent = exports.PageEvent = exports.Theme = exports.UrlMapping = exports.DefaultThemeRenderContext = exports.DefaultTheme = exports.Renderer = exports.Context = exports.Converter = exports.normalizePath = exports.resetReflectionID = exports.Event = exports.EventDispatcher = exports.Application = void 0;
 var application_1 = require("./lib/application");
 Object.defineProperty(exports, "Application", { enumerable: true, get: function () { return application_1.Application; } });
 var events_1 = require("./lib/utils/events");
@@ -40,6 +40,7 @@ Object.defineProperty(exports, "MarkdownEvent", { enumerable: true, get: functio
 var utils_1 = require("./lib/utils");
 Object.defineProperty(exports, "ArgumentsReader", { enumerable: true, get: function () { return utils_1.ArgumentsReader; } });
 Object.defineProperty(exports, "BindOption", { enumerable: true, get: function () { return utils_1.BindOption; } });
+Object.defineProperty(exports, "CommentStyle", { enumerable: true, get: function () { return utils_1.CommentStyle; } });
 Object.defineProperty(exports, "JSX", { enumerable: true, get: function () { return utils_1.JSX; } });
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return utils_1.LogLevel; } });
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return utils_1.Logger; } });

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

@@ -230,7 +230,7 @@ function* lexBlockComment2(file, pos, end) {
         return lookahead;
     }
     function lookaheadExactlyNTicks(pos, n) {
-        if (pos + n >= end) {
+        if (pos + n > end) {
             return false;
         }
         return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";

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

@@ -14,6 +14,7 @@ export interface DeclarationReference {
 }
 export interface Meaning {
     keyword?: MeaningKeyword;
+    label?: string;
     index?: number;
 }
 export interface SymbolReference {
@@ -35,8 +36,5 @@ export declare function parseModuleSource(source: string, pos: number, end: numb
 export declare function parseSymbolReference(source: string, pos: number, end: number): [SymbolReference, number] | undefined;
 export declare function parseComponent(source: string, pos: number, end: number): [string, number] | undefined;
 export declare function parseComponentPath(source: string, pos: number, end: number): readonly [ComponentPath[], number] | undefined;
-export declare function parseMeaning(source: string, pos: number, end: number): [{
-    keyword?: MeaningKeyword;
-    index?: number;
-}, number] | undefined;
+export declare function parseMeaning(source: string, pos: number, end: number): [Meaning, number] | undefined;
 export declare function parseDeclarationReference(source: string, pos: number, end: number): [DeclarationReference, number] | undefined;

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

@@ -34,6 +34,8 @@ const DecimalDigit = "0123456789";
 const HexDigit = DecimalDigit + "abcdefABCDEF";
 const SingleEscapeCharacter = `'"\\bfnrtv`;
 const EscapeCharacter = SingleEscapeCharacter + DecimalDigit + "xu";
+const UserLabelStart = "ABCDEFGHIJKLMNOPQRSTUVWXYZ_";
+const UserLabelCharacter = UserLabelStart + DecimalDigit;
 const SingleEscapeChars = {
     "'": "'",
     '"': '"',
@@ -217,11 +219,17 @@ function parseComponentPath(source, pos, end) {
     return [components, pos];
 }
 exports.parseComponentPath = parseComponentPath;
+// The TSDoc specification permits the first four branches of Meaning. TypeDoc adds the UserLabel
+// branch so that the @label tag can be used with this form of declaration references.
 // Meaning:
 //     `:` MeaningKeyword                            // Indicates the meaning of a symbol (i.e. ':class')
 //     `:` MeaningKeyword `(` DecimalDigits `)`      // Indicates an overloaded meaning (i.e. ':function(1)')
 //     `:` `(` DecimalDigits `)`                     // Shorthand for an overloaded meaning (i.e. `:(1)`)
 //     `:` DecimalDigits                             // Shorthand for an overloaded meaning (i.e. ':1')
+//     `:` UserLabel                                 // Indicates a user defined label via {@label CUSTOM_LABEL}
+//
+// UserLabel:
+//     UserLabelStart UserLabelCharacter*
 function parseMeaning(source, pos, end) {
     if (source[pos++] !== ":")
         return;
@@ -229,6 +237,14 @@ function parseMeaning(source, pos, end) {
     if (keyword) {
         pos += keyword.length;
     }
+    if (!keyword && UserLabelStart.includes(source[pos])) {
+        let lookahead = pos + 1;
+        while (lookahead < end &&
+            UserLabelCharacter.includes(source[lookahead])) {
+            lookahead++;
+        }
+        return [{ label: source.substring(pos, lookahead) }, lookahead];
+    }
     if (pos + 1 < end &&
         source[pos] === "(" &&
         DecimalDigit.includes(source[pos + 1])) {
@@ -242,7 +258,7 @@ function parseMeaning(source, pos, end) {
                     keyword,
                     index: parseInt(source.substring(pos + 1, lookahead)),
                 },
-                pos,
+                lookahead + 1,
             ];
         }
     }
@@ -255,7 +271,7 @@ function parseMeaning(source, pos, end) {
             {
                 index: parseInt(source.substring(pos, lookahead)),
             },
-            pos,
+            lookahead,
         ];
     }
     if (keyword) {

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

@@ -69,6 +69,9 @@ exports.resolveDeclarationReference = resolveDeclarationReference;
 function filterMapByMeaning(reflections, meaning) {
     return (0, utils_1.filterMap)(reflections, (refl) => {
         const kwResolved = resolveKeyword(refl, meaning.keyword) || [];
+        if (meaning.label) {
+            return kwResolved.find((r) => r.label === meaning.label);
+        }
         return kwResolved[meaning.index || 0];
     });
 }

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

@@ -84,7 +84,7 @@ const wantedKinds = {
 function discoverComment(symbol, kind, logger, commentStyle) {
     // For a module comment, we want the first one defined in the file,
     // not the last one, since that will apply to the import or declaration.
-    const reverse = symbol.declarations?.some(ts.isSourceFile);
+    const reverse = !symbol.declarations?.some(ts.isSourceFile);
     const discovered = [];
     for (const decl of symbol.declarations || []) {
         const text = decl.getSourceFile().text;
@@ -105,7 +105,7 @@ function discoverComment(symbol, kind, logger, commentStyle) {
             }
             const comments = collectCommentRanges(ts.getLeadingCommentRanges(text, node.pos));
             if (reverse) {
-                comments?.reverse();
+                comments.reverse();
             }
             const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
             if (selectedDocComment) {

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

@@ -200,7 +200,7 @@ function* lexBlockComment2(file, pos, end) {
         return lookahead;
     }
     function lookaheadExactlyNTicks(pos, n) {
-        if (pos + n >= end) {
+        if (pos + n > end) {
             return false;
         }
         return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";

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

@@ -191,7 +191,7 @@ function* lexCommentString2(file) {
         };
     }
     function lookaheadExactlyNTicks(pos, n) {
-        if (pos + n >= end) {
+        if (pos + n > end) {
             return false;
         }
         return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";

package/dist/lib/converter/plugins/CommentPlugin.js

@@ -196,9 +196,13 @@ let CommentPlugin = class CommentPlugin extends components_1.ConverterComponent
      * @param context  The context object describing the current state the converter is in.
      * @param reflection  The reflection that is currently resolved.
      */
-    onResolve(_context, reflection) {
+    onResolve(context, reflection) {
         if (reflection.comment) {
             reflection.label = extractLabelTag(reflection.comment);
+            if (reflection.label && !/[A-Z_][A-Z0-9_]/.test(reflection.label)) {
+                context.logger.warn(`The label "${reflection.label}" for ${reflection.getFriendlyFullName()} cannot be referenced with a declaration reference. ` +
+                    `Labels may only contain A-Z, 0-9, and _, and may not start with a number.`);
+            }
             mergeSeeTags(reflection.comment);
         }
         if (!(reflection instanceof models_1.DeclarationReflection)) {

package/dist/lib/converter/plugins/InheritDocPlugin.js

@@ -53,6 +53,9 @@ let InheritDocPlugin = class InheritDocPlugin extends components_1.ConverterComp
             if (!source)
                 continue;
             const declRef = (0, declarationReference_1.parseDeclarationReference)(source, 0, source.length);
+            if (!declRef || /\S/.test(source.substring(declRef[1]))) {
+                context.logger.warn(`Declaration reference in @inheritDoc for ${reflection.getFriendlyFullName()} was not fully parsed and may resolve incorrectly.`);
+            }
             let sourceRefl = declRef && (0, declarationReferenceResolver_1.resolveDeclarationReference)(reflection, declRef[0]);
             if (reflection instanceof models_1.SignatureReflection) {
                 // Assumes that if there are overloads, they are declared in the same order as the parent.

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

@@ -6,7 +6,7 @@ export type { IfInternal, NeverIfInternal, Chars } from "./general";
 export { assertNever } from "./general";
 export { CallbackLogger, ConsoleLogger, Logger, LogLevel } from "./loggers";
 export { DefaultMap } from "./map";
-export { ArgumentsReader, BindOption, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, } from "./options";
+export { ArgumentsReader, BindOption, CommentStyle, Options, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, } from "./options";
 export type { ArrayDeclarationOption, BooleanDeclarationOption, DeclarationOption, DeclarationOptionBase, DeclarationOptionToOptionType, KeyToDeclaration, MapDeclarationOption, MixedDeclarationOption, NumberDeclarationOption, FlagsDeclarationOption, OptionsReader, StringDeclarationOption, TypeDocOptionMap, TypeDocOptions, ValidationOptions, TypeDocOptionValues, ParameterTypeToOptionTypeMap, ManuallyValidatedOption, } from "./options";
 export { discoverPlugins, loadPlugins } from "./plugins";
 export { sortReflections } from "./sort";

package/dist/lib/utils/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.sortReflections = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
+exports.Validation = exports.renderElement = exports.Raw = exports.Fragment = exports.JSX = exports.EventHooks = exports.sortReflections = exports.loadPlugins = exports.discoverPlugins = exports.TypeDocReader = exports.TSConfigReader = exports.ParameterType = exports.ParameterHint = exports.Options = exports.CommentStyle = exports.BindOption = exports.ArgumentsReader = exports.DefaultMap = exports.LogLevel = exports.Logger = exports.ConsoleLogger = exports.CallbackLogger = exports.assertNever = exports.writeFileSync = exports.writeFile = exports.readFile = exports.normalizePath = exports.getCommonDirectory = exports.copySync = exports.copy = exports.EventDispatcher = exports.Event = exports.Component = exports.ChildableComponent = exports.AbstractComponent = exports.unique = exports.removeIfPresent = exports.removeIf = exports.partition = exports.insertPrioritySorted = exports.filterMap = void 0;
 var array_1 = require("./array");
 Object.defineProperty(exports, "filterMap", { enumerable: true, get: function () { return array_1.filterMap; } });
 Object.defineProperty(exports, "insertPrioritySorted", { enumerable: true, get: function () { return array_1.insertPrioritySorted; } });
@@ -49,6 +49,7 @@ Object.defineProperty(exports, "DefaultMap", { enumerable: true, get: function (
 var options_1 = require("./options");
 Object.defineProperty(exports, "ArgumentsReader", { enumerable: true, get: function () { return options_1.ArgumentsReader; } });
 Object.defineProperty(exports, "BindOption", { enumerable: true, get: function () { return options_1.BindOption; } });
+Object.defineProperty(exports, "CommentStyle", { enumerable: true, get: function () { return options_1.CommentStyle; } });
 Object.defineProperty(exports, "Options", { enumerable: true, get: function () { return options_1.Options; } });
 Object.defineProperty(exports, "ParameterHint", { enumerable: true, get: function () { return options_1.ParameterHint; } });
 Object.defineProperty(exports, "ParameterType", { enumerable: true, get: function () { return options_1.ParameterType; } });

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

@@ -1,5 +1,5 @@
 export { Options, BindOption } from "./options";
 export type { OptionsReader } from "./options";
 export { ArgumentsReader, TypeDocReader, TSConfigReader } from "./readers";
-export { EmitStrategy, ParameterType, ParameterHint } from "./declaration";
+export { CommentStyle, EmitStrategy, ParameterType, ParameterHint, } from "./declaration";
 export type { TypeDocOptions, TypeDocOptionMap, ValidationOptions, KeyToDeclaration, DeclarationOption, DeclarationOptionBase, StringDeclarationOption, NumberDeclarationOption, BooleanDeclarationOption, ArrayDeclarationOption, MixedDeclarationOption, MapDeclarationOption, FlagsDeclarationOption, DeclarationOptionToOptionType, TypeDocOptionValues, ParameterTypeToOptionTypeMap, ManuallyValidatedOption, } from "./declaration";

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ParameterHint = exports.ParameterType = exports.EmitStrategy = exports.TSConfigReader = exports.TypeDocReader = exports.ArgumentsReader = exports.BindOption = exports.Options = void 0;
+exports.ParameterHint = exports.ParameterType = exports.EmitStrategy = exports.CommentStyle = exports.TSConfigReader = exports.TypeDocReader = exports.ArgumentsReader = exports.BindOption = exports.Options = void 0;
 var options_1 = require("./options");
 Object.defineProperty(exports, "Options", { enumerable: true, get: function () { return options_1.Options; } });
 Object.defineProperty(exports, "BindOption", { enumerable: true, get: function () { return options_1.BindOption; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "ArgumentsReader", { enumerable: true, get: funct
 Object.defineProperty(exports, "TypeDocReader", { enumerable: true, get: function () { return readers_1.TypeDocReader; } });
 Object.defineProperty(exports, "TSConfigReader", { enumerable: true, get: function () { return readers_1.TSConfigReader; } });
 var declaration_1 = require("./declaration");
+Object.defineProperty(exports, "CommentStyle", { enumerable: true, get: function () { return declaration_1.CommentStyle; } });
 Object.defineProperty(exports, "EmitStrategy", { enumerable: true, get: function () { return declaration_1.EmitStrategy; } });
 Object.defineProperty(exports, "ParameterType", { enumerable: true, get: function () { return declaration_1.ParameterType; } });
 Object.defineProperty(exports, "ParameterHint", { enumerable: true, get: function () { return declaration_1.ParameterHint; } });

package/package.json

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