typedoc 0.23.0-beta.5 → 0.23.0

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.d.ts

@@ -0,0 +1,3 @@
+import { Reflection } from "../../models";
+import type { DeclarationReference } from "./declarationReference";
+export declare function resolveDeclarationReference(reflection: Reflection, ref: DeclarationReference): Reflection | undefined;

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

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDeclarationReference = void 0;
+const assert_1 = require("assert");
+const models_1 = require("../../models");
+const utils_1 = require("../../utils");
+function resolveDeclarationReference(reflection, ref) {
+    let high = [];
+    let low = [];
+    if (ref.moduleSource) {
+        high =
+            reflection.project.children?.filter((c) => c.kindOf(models_1.ReflectionKind.SomeModule) &&
+                c.name === ref.moduleSource) || [];
+    }
+    else if (ref.resolutionStart === "global") {
+        high.push(reflection.project);
+    }
+    else {
+        (0, assert_1.ok)(ref.resolutionStart === "local");
+        // TypeScript's behavior is to first try to resolve links via variable scope, and then
+        // if the link still hasn't been found, check either siblings (if comment belongs to a member)
+        // or otherwise children.
+        let refl = reflection;
+        if (refl.kindOf(models_1.ReflectionKind.ExportContainer)) {
+            high.push(refl);
+        }
+        while (refl.parent) {
+            refl = refl.parent;
+            if (refl.kindOf(models_1.ReflectionKind.ExportContainer)) {
+                high.push(refl);
+            }
+        }
+        if (reflection.kindOf(models_1.ReflectionKind.SomeMember)) {
+            high.push(reflection.parent);
+        }
+        else if (reflection.kindOf(models_1.ReflectionKind.SomeSignature) &&
+            reflection.parent.kindOf(models_1.ReflectionKind.SomeMember)) {
+            high.push(reflection.parent.parent);
+        }
+        else if (high[0] !== reflection) {
+            high.push(reflection);
+        }
+    }
+    if (ref.symbolReference) {
+        for (const part of ref.symbolReference.path || []) {
+            const high2 = high;
+            high = [];
+            const low2 = low;
+            low = [];
+            for (const refl of high2) {
+                const resolved = resolveSymbolReferencePart(refl, part);
+                high.push(...resolved.high);
+                low.push(...resolved.low);
+            }
+            for (const refl of low2) {
+                const resolved = resolveSymbolReferencePart(refl, part);
+                low.push(...resolved.high);
+                low.push(...resolved.low);
+            }
+        }
+        if (ref.symbolReference.meaning) {
+            high = filterMapByMeaning(high, ref.symbolReference.meaning);
+            low = filterMapByMeaning(low, ref.symbolReference.meaning);
+        }
+    }
+    return high[0] || low[0];
+}
+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];
+    });
+}
+function resolveKeyword(refl, kw) {
+    switch (kw) {
+        case undefined:
+            return refl instanceof models_1.DeclarationReflection && refl.signatures
+                ? refl.signatures
+                : [refl];
+        case "class":
+            if (refl.kindOf(models_1.ReflectionKind.Class))
+                return [refl];
+            break;
+        case "interface":
+            if (refl.kindOf(models_1.ReflectionKind.Interface))
+                return [refl];
+            break;
+        case "type":
+            if (refl.kindOf(models_1.ReflectionKind.SomeType))
+                return [refl];
+            break;
+        case "enum":
+            if (refl.kindOf(models_1.ReflectionKind.Enum))
+                return [refl];
+            break;
+        case "namespace":
+            if (refl.kindOf(models_1.ReflectionKind.SomeModule))
+                return [refl];
+            break;
+        case "function":
+            if (refl.kindOf(models_1.ReflectionKind.FunctionOrMethod)) {
+                return refl.signatures;
+            }
+            break;
+        case "var":
+            if (refl.kindOf(models_1.ReflectionKind.Variable))
+                return [refl];
+            break;
+        case "new":
+        case "constructor":
+            if (refl.kindOf(models_1.ReflectionKind.ClassOrInterface | models_1.ReflectionKind.TypeLiteral)) {
+                const ctor = refl.children?.find((c) => c.kindOf(models_1.ReflectionKind.Constructor));
+                return ctor?.signatures;
+            }
+            break;
+        case "member":
+            if (refl.kindOf(models_1.ReflectionKind.SomeMember))
+                return [refl];
+            break;
+        case "event":
+            // Never resolve. Nobody should use this.
+            // It's required by the grammar, but is not documented by TypeDoc
+            // nor by the comments in the grammar.
+            break;
+        case "call":
+            return refl.signatures;
+        case "index":
+            if (refl.indexSignature) {
+                return [refl.indexSignature];
+            }
+            break;
+        case "complex":
+            if (refl.kindOf(models_1.ReflectionKind.SomeType))
+                return [refl];
+            break;
+    }
+}
+function resolveSymbolReferencePart(refl, path) {
+    let high = [];
+    let low = [];
+    if (!(refl instanceof models_1.ContainerReflection) || !refl.children) {
+        return { high, low };
+    }
+    switch (path.navigation) {
+        // Grammar says resolve via "exports"... as always, reality is more complicated.
+        // Check exports first, but also allow this as a general purpose "some child" operator
+        // so that resolution doesn't behave very poorly with projects using JSDoc style resolution.
+        // Also is more consistent with how TypeScript resolves link tags.
+        case ".":
+            high = refl.children.filter((r) => r.name === path.path &&
+                (r.kindOf(models_1.ReflectionKind.SomeExport) || r.flags.isStatic));
+            low = refl.children.filter((r) => r.name === path.path &&
+                (!r.kindOf(models_1.ReflectionKind.SomeExport) || !r.flags.isStatic));
+            break;
+        // Resolve via "members", interface children, class instance properties/accessors/methods,
+        // enum members, type literal properties
+        case "#":
+            high = refl.children.filter((r) => {
+                return (r.name === path.path &&
+                    r.kindOf(models_1.ReflectionKind.SomeMember) &&
+                    !r.flags.isStatic);
+            });
+            break;
+        // Resolve via "locals"... treat this as a stricter `.` which only supports traversing
+        // module/namespace exports since TypeDoc doesn't support documenting locals.
+        case "~":
+            if (refl.kindOf(models_1.ReflectionKind.SomeModule | models_1.ReflectionKind.Project)) {
+                high = refl.children.filter((r) => r.name === path.path);
+            }
+            break;
+    }
+    return { high, low };
+}

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/parser.js

@@ -153,7 +153,7 @@ function blockContent(comment, lexer, config, warning) {
                 break;
             case lexer_1.TokenSyntaxKind.Tag:
                 if (next.text === "@inheritdoc") {
-                    warning("The @inheritDoc tag should be properly capitalized.");
+                    warning("The @inheritDoc tag should be properly capitalized");
                     next.text = "@inheritDoc";
                 }
                 if (config.modifierTags.has(next.text)) {

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/CategoryPlugin.d.ts

@@ -10,7 +10,8 @@ export declare class CategoryPlugin extends ConverterComponent {
     defaultCategory: string;
     categoryOrder: string[];
     categorizeByGroup: boolean;
-    searchCategoryBoosts: Record<string, number> | undefined;
+    boosts: Record<string, number>;
+    usedBoosts: Set<string>;
     static defaultCategory: string;
     static WEIGHTS: string[];
     /**
@@ -45,9 +46,7 @@ export declare class CategoryPlugin extends ConverterComponent {
      *   relevance boost to be used when searching
      * @returns An array containing all children of the given reflection categorized
      */
-    static getReflectionCategories(reflections: DeclarationReflection[], categorySearchBoosts: {
-        [key: string]: number;
-    } | undefined): ReflectionCategory[];
+    getReflectionCategories(reflections: DeclarationReflection[]): ReflectionCategory[];
     /**
      * Return the category of a given reflection.
      *
@@ -57,7 +56,7 @@ export declare class CategoryPlugin extends ConverterComponent {
      * @privateRemarks
      * If you change this, also update getGroups in GroupPlugin accordingly.
      */
-    static getCategories(reflection: DeclarationReflection): Set<string>;
+    getCategories(reflection: DeclarationReflection): Set<string>;
     /**
      * Callback used to sort categories by name.
      *

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

@@ -19,6 +19,10 @@ const utils_1 = require("../../utils");
  * The handler sets the ´category´ property of all reflections.
  */
 let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_1.ConverterComponent {
+    constructor() {
+        super(...arguments);
+        this.usedBoosts = new Set();
+    }
     /**
      * Create a new CategoryPlugin instance.
      */
@@ -60,6 +64,15 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
     onEndResolve(context) {
         const project = context.project;
         this.categorize(project);
+        const unusedBoosts = new Set(Object.keys(this.boosts));
+        for (const boost of this.usedBoosts) {
+            unusedBoosts.delete(boost);
+        }
+        this.usedBoosts.clear();
+        if (unusedBoosts.size) {
+            context.logger.warn(`Not all categories specified in searchCategoryBoosts were used in the documentation.` +
+                ` The unused categories were:\n\t${Array.from(unusedBoosts).join("\n\t")}`);
+        }
     }
     categorize(obj) {
         if (this.categorizeByGroup) {
@@ -76,7 +89,7 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
         obj.groups.forEach((group) => {
             if (group.categories)
                 return;
-            group.categories = CategoryPlugin_1.getReflectionCategories(group.children, this.searchCategoryBoosts);
+            group.categories = this.getReflectionCategories(group.children);
             if (group.categories && group.categories.length > 1) {
                 group.categories.sort(CategoryPlugin_1.sortCatCallback);
             }
@@ -91,7 +104,7 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
         if (!obj.children || obj.children.length === 0 || obj.categories) {
             return;
         }
-        obj.categories = CategoryPlugin_1.getReflectionCategories(obj.children, this.searchCategoryBoosts);
+        obj.categories = this.getReflectionCategories(obj.children);
         if (obj.categories && obj.categories.length > 1) {
             obj.categories.sort(CategoryPlugin_1.sortCatCallback);
         }
@@ -109,11 +122,11 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
      *   relevance boost to be used when searching
      * @returns An array containing all children of the given reflection categorized
      */
-    static getReflectionCategories(reflections, categorySearchBoosts) {
+    getReflectionCategories(reflections) {
         const categories = [];
         let defaultCat;
         reflections.forEach((child) => {
-            const childCategories = CategoryPlugin_1.getCategories(child);
+            const childCategories = this.getCategories(child);
             if (childCategories.size === 0) {
                 if (!defaultCat) {
                     defaultCat = categories.find((category) => category.title === CategoryPlugin_1.defaultCategory);
@@ -127,11 +140,6 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
             }
             for (const childCat of childCategories) {
                 let category = categories.find((cat) => cat.title === childCat);
-                const catBoost = categorySearchBoosts?.[category?.title ?? -1];
-                if (catBoost != undefined) {
-                    child.relevanceBoost =
-                        (child.relevanceBoost ?? 1) * catBoost;
-                }
                 if (category) {
                     category.children.push(child);
                     continue;
@@ -152,7 +160,7 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
      * @privateRemarks
      * If you change this, also update getGroups in GroupPlugin accordingly.
      */
-    static getCategories(reflection) {
+    getCategories(reflection) {
         const categories = new Set();
         function extractCategoryTags(comment) {
             if (!comment)
@@ -176,6 +184,13 @@ let CategoryPlugin = CategoryPlugin_1 = class CategoryPlugin extends components_
             }
         }
         categories.delete("");
+        for (const cat of categories) {
+            if (cat in this.boosts) {
+                this.usedBoosts.add(cat);
+                reflection.relevanceBoost =
+                    (reflection.relevanceBoost ?? 1) * this.boosts[cat];
+            }
+        }
         return categories;
     }
     /**
@@ -220,7 +235,7 @@ __decorate([
 ], CategoryPlugin.prototype, "categorizeByGroup", void 0);
 __decorate([
     (0, utils_1.BindOption)("searchCategoryBoosts")
-], CategoryPlugin.prototype, "searchCategoryBoosts", void 0);
+], CategoryPlugin.prototype, "boosts", void 0);
 CategoryPlugin = CategoryPlugin_1 = __decorate([
     (0, components_1.Component)({ name: "category" })
 ], CategoryPlugin);

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/GroupPlugin.d.ts

@@ -27,6 +27,8 @@ export declare class GroupPlugin extends ConverterComponent {
     };
     /** @internal */
     sortStrategies: SortStrategy[];
+    boosts: Record<string, number>;
+    usedBoosts: Set<string>;
     /**
      * Create a new GroupPlugin instance.
      */
@@ -51,7 +53,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @privateRemarks
      * If you change this, also update getCategories in CategoryPlugin accordingly.
      */
-    static getGroups(reflection: DeclarationReflection): Set<string>;
+    getGroups(reflection: DeclarationReflection): Set<string>;
     /**
      * Create a grouped representation of the given list of reflections.
      *
@@ -60,7 +62,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @param reflections  The reflections that should be grouped.
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
-    static getReflectionGroups(reflections: DeclarationReflection[]): ReflectionGroup[];
+    getReflectionGroups(reflections: DeclarationReflection[]): ReflectionGroup[];
     /**
      * Transform the internal typescript kind identifier into a human readable version.
      *

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

@@ -21,6 +21,10 @@ const models_1 = require("../../models");
  * The handler sets the `groups` property of all container reflections.
  */
 let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.ConverterComponent {
+    constructor() {
+        super(...arguments);
+        this.usedBoosts = new Set();
+    }
     /**
      * Create a new GroupPlugin instance.
      */
@@ -49,13 +53,23 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
      */
     onEndResolve(context) {
         this.group(context.project);
+        const unusedBoosts = new Set(Object.keys(this.boosts));
+        for (const boost of this.usedBoosts) {
+            unusedBoosts.delete(boost);
+        }
+        this.usedBoosts.clear();
+        if (unusedBoosts.size &&
+            this.application.options.isSet("searchGroupBoosts")) {
+            context.logger.warn(`Not all groups specified in searchGroupBoosts were used in the documentation.` +
+                ` The unused groups were:\n\t${Array.from(unusedBoosts).join("\n\t")}`);
+        }
     }
     group(reflection) {
         if (reflection.children &&
             reflection.children.length > 0 &&
             !reflection.groups) {
             (0, sort_1.sortReflections)(reflection.children, this.sortStrategies);
-            reflection.groups = GroupPlugin_1.getReflectionGroups(reflection.children);
+            reflection.groups = this.getReflectionGroups(reflection.children);
         }
     }
     /**
@@ -64,7 +78,7 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
      * @privateRemarks
      * If you change this, also update getCategories in CategoryPlugin accordingly.
      */
-    static getGroups(reflection) {
+    getGroups(reflection) {
         const groups = new Set();
         function extractGroupTags(comment) {
             if (!comment)
@@ -91,6 +105,13 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
         if (groups.size === 0) {
             groups.add(GroupPlugin_1.getKindPlural(reflection.kind));
         }
+        for (const group of groups) {
+            if (group in this.boosts) {
+                this.usedBoosts.add(group);
+                reflection.relevanceBoost =
+                    (reflection.relevanceBoost ?? 1) * this.boosts[group];
+            }
+        }
         return groups;
     }
     /**
@@ -101,10 +122,10 @@ let GroupPlugin = GroupPlugin_1 = class GroupPlugin extends components_1.Convert
      * @param reflections  The reflections that should be grouped.
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
-    static getReflectionGroups(reflections) {
+    getReflectionGroups(reflections) {
         const groups = new Map();
         reflections.forEach((child) => {
-            for (const name of GroupPlugin_1.getGroups(child)) {
+            for (const name of this.getGroups(child)) {
                 let group = groups.get(name);
                 if (!group) {
                     group = new ReflectionGroup_1.ReflectionGroup(name);
@@ -175,6 +196,9 @@ GroupPlugin.PLURALS = {
 __decorate([
     (0, utils_1.BindOption)("sort")
 ], GroupPlugin.prototype, "sortStrategies", void 0);
+__decorate([
+    (0, utils_1.BindOption)("searchGroupBoosts")
+], GroupPlugin.prototype, "boosts", void 0);
 GroupPlugin = GroupPlugin_1 = __decorate([
     (0, components_1.Component)({ name: "group" })
 ], GroupPlugin);

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

@@ -12,6 +12,8 @@ const components_1 = require("../components");
 const converter_1 = require("../converter");
 const utils_1 = require("../../utils");
 const array_1 = require("../../utils/array");
+const declarationReference_1 = require("../comments/declarationReference");
+const declarationReferenceResolver_1 = require("../comments/declarationReferenceResolver");
 /**
  * A plugin that handles `@inheritDoc` tags by copying documentation from another API item.
  * It is NOT responsible for handling bare JSDoc style `@inheritDoc` tags which do not specify
@@ -50,7 +52,11 @@ let InheritDocPlugin = class InheritDocPlugin extends components_1.ConverterComp
             const source = extractInheritDocTagReference(reflection);
             if (!source)
                 continue;
-            let sourceRefl = source && reflection.findReflectionByName(source);
+            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.
                 // TS doesn't check this, but if a user messes this up then they are almost