typedoc 0.24.0-beta.1 → 0.24.0-beta.3

package/dist/lib/converter/factories/signature.js

@@ -1,33 +1,10 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTypeParamReflection = exports.convertTypeParameterNodes = exports.convertParameterNodes = exports.createSignature = void 0;
-const ts = __importStar(require("typescript"));
+const typescript_1 = __importDefault(require("typescript"));
 const assert_1 = __importDefault(require("assert"));
 const models_1 = require("../../models");
 const converter_events_1 = require("../converter-events");
@@ -46,12 +23,18 @@ function createSignature(context, kind, signature, symbol, declaration) {
     if (symbol && declaration) {
         context.project.registerSymbolId(sigRef, new ReflectionSymbolId_1.ReflectionSymbolId(symbol, declaration));
     }
-    // If we are creating signatures for a variable and the variable has a comment associated with it
-    // then we should prefer that variable's comment over any comment on the signature. The comment plugin
+    // If we are creating signatures for a variable or property and it has a comment associated with it
+    // then we should prefer that comment over any comment on the signature. The comment plugin
     // will copy the comment down if this signature doesn't have one, so don't set one.
+    let parentReflection = context.scope;
+    if (parentReflection.kindOf(models_1.ReflectionKind.TypeLiteral) &&
+        parentReflection.parent instanceof models_1.DeclarationReflection) {
+        parentReflection = parentReflection.parent;
+    }
     if (declaration &&
-        (!context.scope.comment ||
-            !(context.scope.conversionFlags & models_1.ConversionFlags.VariableSource))) {
+        (!parentReflection.comment ||
+            !(parentReflection.conversionFlags &
+                models_1.ConversionFlags.VariableOrPropertySource))) {
         sigRef.comment = (0, comments_1.getSignatureComment)(declaration, context.converter.config, context.logger, context.converter.commentStyle);
     }
     sigRef.typeParameters = convertTypeParameters(sigRefCtx, sigRef, signature.typeParameters);
@@ -67,7 +50,7 @@ function createSignature(context, kind, signature, symbol, declaration) {
         sigRef.type = new models_1.IntrinsicType("void");
     }
     else {
-        sigRef.type = context.converter.convertType(sigRefCtx, (declaration?.kind === ts.SyntaxKind.FunctionDeclaration &&
+        sigRef.type = context.converter.convertType(sigRefCtx, (declaration?.kind === typescript_1.default.SyntaxKind.FunctionDeclaration &&
             declaration.type) ||
             signature.getReturnType());
     }
@@ -92,10 +75,10 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
     return parameters.map((param, i) => {
         const declaration = param.valueDeclaration;
         (0, assert_1.default)(!declaration ||
-            ts.isParameter(declaration) ||
-            ts.isJSDocParameterTag(declaration));
+            typescript_1.default.isParameter(declaration) ||
+            typescript_1.default.isJSDocParameterTag(declaration));
         const paramRefl = new models_1.ParameterReflection(/__\d+/.test(param.name) ? "__namedParameters" : param.name, models_1.ReflectionKind.Parameter, sigRef);
-        if (declaration && ts.isJSDocParameterTag(declaration)) {
+        if (declaration && typescript_1.default.isJSDocParameterTag(declaration)) {
             paramRefl.comment = (0, comments_1.getJsDocComment)(declaration, context.converter.config, context.logger);
         }
         paramRefl.comment || (paramRefl.comment = (0, comments_1.getComment)(param, paramRefl.kind, context.converter.config, context.logger, context.converter.commentStyle));
@@ -111,9 +94,9 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         paramRefl.type = context.converter.convertType(context.withScope(paramRefl), type);
         let isOptional = false;
         if (declaration) {
-            isOptional = ts.isParameter(declaration)
+            isOptional = typescript_1.default.isParameter(declaration)
                 ? !!declaration.questionToken ||
-                    ts
+                    typescript_1.default
                         .getJSDocParameterTags(declaration)
                         .some((tag) => tag.isBracketed)
                 : declaration.isBracketed;
@@ -127,10 +110,10 @@ function convertParameters(context, sigRef, parameters, parameterNodes) {
         // because the method body uses `arguments`... which is always a rest argument
         let isRest = true;
         if (declaration) {
-            isRest = ts.isParameter(declaration)
+            isRest = typescript_1.default.isParameter(declaration)
                 ? !!declaration.dotDotDotToken
                 : !!declaration.typeExpression &&
-                    ts.isJSDocVariadicType(declaration.typeExpression.type);
+                    typescript_1.default.isJSDocVariadicType(declaration.typeExpression.type);
         }
         paramRefl.setFlag(models_1.ReflectionFlag.Rest, isRest);
         return paramRefl;
@@ -141,13 +124,13 @@ function convertParameterNodes(context, sigRef, parameters) {
         const paramRefl = new models_1.ParameterReflection(/__\d+/.test(param.name.getText())
             ? "__namedParameters"
             : param.name.getText(), models_1.ReflectionKind.Parameter, sigRef);
-        if (ts.isJSDocParameterTag(param)) {
+        if (typescript_1.default.isJSDocParameterTag(param)) {
             paramRefl.comment = (0, comments_1.getJsDocComment)(param, context.converter.config, context.logger);
         }
         context.registerReflection(paramRefl, context.getSymbolAtLocation(param));
         context.trigger(converter_events_1.ConverterEvents.CREATE_PARAMETER, paramRefl);
-        paramRefl.type = context.converter.convertType(context.withScope(paramRefl), ts.isParameter(param) ? param.type : param.typeExpression?.type);
-        const isOptional = ts.isParameter(param)
+        paramRefl.type = context.converter.convertType(context.withScope(paramRefl), typescript_1.default.isParameter(param) ? param.type : param.typeExpression?.type);
+        const isOptional = typescript_1.default.isParameter(param)
             ? !!param.questionToken
             : param.isBracketed;
         if (isOptional) {
@@ -155,10 +138,10 @@ function convertParameterNodes(context, sigRef, parameters) {
         }
         paramRefl.defaultValue = (0, convert_expression_1.convertDefaultValue)(param);
         paramRefl.setFlag(models_1.ReflectionFlag.Optional, isOptional);
-        paramRefl.setFlag(models_1.ReflectionFlag.Rest, ts.isParameter(param)
+        paramRefl.setFlag(models_1.ReflectionFlag.Rest, typescript_1.default.isParameter(param)
             ? !!param.dotDotDotToken
             : !!param.typeExpression &&
-                ts.isJSDocVariadicType(param.typeExpression.type));
+                typescript_1.default.isJSDocVariadicType(param.typeExpression.type));
         return paramRefl;
     });
 }
@@ -169,7 +152,7 @@ function convertTypeParameters(context, parent, parameters) {
         const defaultT = param.getDefault();
         // There's no way to determine directly from a ts.TypeParameter what it's variance modifiers are
         // so unfortunately we have to go back to the node for this...
-        const variance = getVariance(param.getSymbol()?.declarations?.find(ts.isTypeParameterDeclaration)
+        const variance = getVariance(param.getSymbol()?.declarations?.find(typescript_1.default.isTypeParameterDeclaration)
             ?.modifiers);
         const paramRefl = new models_1.TypeParameterReflection(param.symbol.name, parent, variance);
         const paramCtx = context.withScope(paramRefl);
@@ -198,7 +181,7 @@ function createTypeParamReflection(param, context) {
         ? context.converter.convertType(paramScope, param.default)
         : void 0;
     context.registerReflection(paramRefl, param.symbol);
-    if (ts.isJSDocTemplateTag(param.parent)) {
+    if (typescript_1.default.isJSDocTemplateTag(param.parent)) {
         paramRefl.comment = (0, comments_1.getJsDocComment)(param.parent, context.converter.config, context.logger);
     }
     context.trigger(converter_events_1.ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl, param);
@@ -206,8 +189,8 @@ function createTypeParamReflection(param, context) {
 }
 exports.createTypeParamReflection = createTypeParamReflection;
 function getVariance(modifiers) {
-    const hasIn = modifiers?.some((mod) => mod.kind === ts.SyntaxKind.InKeyword);
-    const hasOut = modifiers?.some((mod) => mod.kind === ts.SyntaxKind.OutKeyword);
+    const hasIn = modifiers?.some((mod) => mod.kind === typescript_1.default.SyntaxKind.InKeyword);
+    const hasOut = modifiers?.some((mod) => mod.kind === typescript_1.default.SyntaxKind.OutKeyword);
     if (hasIn && hasOut) {
         return models_1.VarianceModifier.inOut;
     }
@@ -221,23 +204,23 @@ function getVariance(modifiers) {
 function convertPredicate(predicate, context) {
     let name;
     switch (predicate.kind) {
-        case ts.TypePredicateKind.This:
-        case ts.TypePredicateKind.AssertsThis:
+        case typescript_1.default.TypePredicateKind.This:
+        case typescript_1.default.TypePredicateKind.AssertsThis:
             name = "this";
             break;
-        case ts.TypePredicateKind.Identifier:
-        case ts.TypePredicateKind.AssertsIdentifier:
+        case typescript_1.default.TypePredicateKind.Identifier:
+        case typescript_1.default.TypePredicateKind.AssertsIdentifier:
             name = predicate.parameterName;
             break;
     }
     let asserts;
     switch (predicate.kind) {
-        case ts.TypePredicateKind.This:
-        case ts.TypePredicateKind.Identifier:
+        case typescript_1.default.TypePredicateKind.This:
+        case typescript_1.default.TypePredicateKind.Identifier:
             asserts = false;
             break;
-        case ts.TypePredicateKind.AssertsThis:
-        case ts.TypePredicateKind.AssertsIdentifier:
+        case typescript_1.default.TypePredicateKind.AssertsThis:
+        case typescript_1.default.TypePredicateKind.AssertsIdentifier:
             asserts = true;
             break;
     }

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

@@ -3,4 +3,5 @@ export { Converter } from "./converter";
 export type { CommentParserConfig } from "./comments/index";
 export { convertDefaultValue, convertExpression } from "./convert-expression";
 export type { DeclarationReference, SymbolReference, ComponentPath, Meaning, MeaningKeyword, } from "./comments/declarationReference";
+export type { ExternalSymbolResolver, ExternalResolveResult, } from "./comments/linkResolver";
 import "./plugins/index";

package/dist/lib/converter/jsdoc.d.ts

@@ -1,4 +1,4 @@
-import * as ts from "typescript";
+import ts from "typescript";
 import type { Context } from "./context";
 export declare function convertJsDocAlias(context: Context, symbol: ts.Symbol, declaration: ts.JSDocTypedefTag | ts.JSDocEnumTag, exportSymbol?: ts.Symbol): void;
 export declare function convertJsDocCallback(context: Context, symbol: ts.Symbol, declaration: ts.JSDocCallbackTag, exportSymbol?: ts.Symbol): void;

package/dist/lib/converter/jsdoc.js

@@ -2,33 +2,13 @@
 // Converter functions for JSDoc defined types
 // @typedef
 // @callback
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertJsDocCallback = exports.convertJsDocAlias = void 0;
 const assert_1 = require("assert");
-const ts = __importStar(require("typescript"));
+const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../models");
 const ReflectionSymbolId_1 = require("../models/reflections/ReflectionSymbolId");
 const comments_1 = require("./comments");
@@ -36,7 +16,7 @@ const converter_events_1 = require("./converter-events");
 const signature_1 = require("./factories/signature");
 function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
     if (declaration.typeExpression &&
-        ts.isJSDocTypeLiteral(declaration.typeExpression)) {
+        typescript_1.default.isJSDocTypeLiteral(declaration.typeExpression)) {
         convertJsDocInterface(context, declaration, symbol, exportSymbol);
         return;
     }
@@ -96,7 +76,7 @@ function convertJsDocSignature(context, node) {
 }
 function convertTemplateParameters(context, node) {
     (0, assert_1.ok)(context.scope instanceof models_1.DeclarationReflection);
-    context.scope.typeParameters = convertTemplateParameterNodes(context, node.tags?.filter(ts.isJSDocTemplateTag));
+    context.scope.typeParameters = convertTemplateParameterNodes(context, node.tags?.filter(typescript_1.default.isJSDocTemplateTag));
 }
 function convertTemplateParameterNodes(context, nodes) {
     const params = (nodes ?? []).flatMap((tag) => tag.typeParameters);
@@ -104,31 +84,31 @@ function convertTemplateParameterNodes(context, nodes) {
 }
 function getTypedefReExportTarget(context, declaration) {
     const typeExpression = declaration.typeExpression;
-    if (!ts.isJSDocTypedefTag(declaration) ||
+    if (!typescript_1.default.isJSDocTypedefTag(declaration) ||
         !typeExpression ||
-        ts.isJSDocTypeLiteral(typeExpression) ||
-        !ts.isImportTypeNode(typeExpression.type) ||
+        typescript_1.default.isJSDocTypeLiteral(typeExpression) ||
+        !typescript_1.default.isImportTypeNode(typeExpression.type) ||
         !typeExpression.type.qualifier ||
-        !ts.isIdentifier(typeExpression.type.qualifier)) {
+        !typescript_1.default.isIdentifier(typeExpression.type.qualifier)) {
         return;
     }
     const targetSymbol = context.expectSymbolAtLocation(typeExpression.type.qualifier);
     const decl = targetSymbol.declarations?.[0];
     if (!decl ||
-        !(ts.isTypeAliasDeclaration(decl) ||
-            ts.isInterfaceDeclaration(decl) ||
-            ts.isJSDocTypedefTag(decl) ||
-            ts.isJSDocCallbackTag(decl))) {
+        !(typescript_1.default.isTypeAliasDeclaration(decl) ||
+            typescript_1.default.isInterfaceDeclaration(decl) ||
+            typescript_1.default.isJSDocTypedefTag(decl) ||
+            typescript_1.default.isJSDocCallbackTag(decl))) {
         return;
     }
-    const targetParams = ts.getEffectiveTypeParameterDeclarations(decl);
-    const localParams = ts.getEffectiveTypeParameterDeclarations(declaration);
+    const targetParams = typescript_1.default.getEffectiveTypeParameterDeclarations(decl);
+    const localParams = typescript_1.default.getEffectiveTypeParameterDeclarations(declaration);
     const localArgs = typeExpression.type.typeArguments || [];
     // If we have type parameters, ensure they are forwarding parameters with no transformations.
     // This doesn't check constraints since they aren't checked in JSDoc types.
     if (targetParams.length !== localParams.length ||
-        localArgs.some((arg, i) => !ts.isTypeReferenceNode(arg) ||
-            !ts.isIdentifier(arg.typeName) ||
+        localArgs.some((arg, i) => !typescript_1.default.isTypeReferenceNode(arg) ||
+            !typescript_1.default.isIdentifier(arg.typeName) ||
             arg.typeArguments ||
             localParams[i]?.name.text !== arg.typeName.text)) {
         return;

package/dist/lib/converter/plugins/CommentPlugin.d.ts

@@ -61,6 +61,8 @@ export declare class CommentPlugin extends ConverterComponent {
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeNotDocumented: boolean;
+    private _excludeKinds;
+    private get excludeNotDocumentedKinds();
     /**
      * Create a new CommentPlugin instance.
      */

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

@@ -89,6 +89,12 @@ const NEVER_RENDERED = [
  *
  */
 let CommentPlugin = class CommentPlugin extends components_1.ConverterComponent {
+    get excludeNotDocumentedKinds() {
+        this._excludeKinds ?? (this._excludeKinds = this.application.options
+            .getValue("excludeNotDocumentedKinds")
+            .reduce((a, b) => a | models_1.ReflectionKind[b], 0));
+        return this._excludeKinds;
+    }
     /**
      * Create a new CommentPlugin instance.
      */
@@ -99,6 +105,9 @@ let CommentPlugin = class CommentPlugin extends components_1.ConverterComponent
             [converter_1.Converter.EVENT_CREATE_TYPE_PARAMETER]: this.onCreateTypeParameter,
             [converter_1.Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
             [converter_1.Converter.EVENT_RESOLVE]: this.onResolve,
+            [converter_1.Converter.EVENT_END]: () => {
+                this._excludeKinds = undefined;
+            },
         });
     }
     /**
@@ -335,12 +344,22 @@ let CommentPlugin = class CommentPlugin extends components_1.ConverterComponent
             return true;
         }
         if (!comment) {
+            // We haven't moved comments from the parent for signatures without a direct
+            // comment, so don't exclude those due to not being documented.
+            if (reflection.kindOf(models_1.ReflectionKind.CallSignature |
+                models_1.ReflectionKind.ConstructorSignature) &&
+                reflection.parent?.comment) {
+                return false;
+            }
             if (this.excludeNotDocumented) {
                 // Don't let excludeNotDocumented remove parameters.
                 if (!(reflection instanceof models_1.DeclarationReflection) &&
                     !(reflection instanceof models_1.SignatureReflection)) {
                     return false;
                 }
+                if (!reflection.kindOf(this.excludeNotDocumentedKinds)) {
+                    return false;
+                }
                 // excludeNotDocumented should hide a module only if it has no visible children
                 if (reflection.kindOf(models_1.ReflectionKind.SomeModule)) {
                     if (!reflection.children) {
@@ -348,10 +367,6 @@ let CommentPlugin = class CommentPlugin extends components_1.ConverterComponent
                     }
                     return reflection.children.every((child) => this.isHidden(child));
                 }
-                // enum members should all be included if the parent enum is documented
-                if (reflection.kind === models_1.ReflectionKind.EnumMember) {
-                    return false;
-                }
                 // signature containers should only be hidden if all their signatures are hidden
                 if (reflection.kindOf(models_1.ReflectionKind.SignatureContainer)) {
                     return reflection

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

@@ -1,36 +1,16 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImplementsPlugin = void 0;
-const ts = __importStar(require("typescript"));
+const typescript_1 = __importDefault(require("typescript"));
 const application_events_1 = require("../../application-events");
 const index_1 = require("../../models/reflections/index");
 const types_1 = require("../../models/types");
@@ -174,7 +154,7 @@ let ImplementsPlugin = class ImplementsPlugin extends components_1.ConverterComp
         }
         const declaration = symbol
             .getDeclarations()
-            ?.find((n) => ts.isClassDeclaration(n) || ts.isInterfaceDeclaration(n));
+            ?.find((n) => typescript_1.default.isClassDeclaration(n) || typescript_1.default.isInterfaceDeclaration(n));
         if (!declaration) {
             return;
         }
@@ -195,7 +175,7 @@ let ImplementsPlugin = class ImplementsPlugin extends components_1.ConverterComp
             return;
         }
         if (reflection.kind === index_1.ReflectionKind.Constructor) {
-            const ctor = info.declaration.members.find(ts.isConstructorDeclaration);
+            const ctor = info.declaration.members.find(typescript_1.default.isConstructorDeclaration);
             constructorInheritance(context, reflection, info.declaration, ctor);
             return;
         }
@@ -212,7 +192,7 @@ let ImplementsPlugin = class ImplementsPlugin extends components_1.ConverterComp
         out: for (const clause of info.declaration.heritageClauses ?? []) {
             // No point checking implemented types for static members, they won't exist.
             if (reflection.flags.isStatic &&
-                clause.token === ts.SyntaxKind.ImplementsKeyword) {
+                clause.token === typescript_1.default.SyntaxKind.ImplementsKeyword) {
                 continue;
             }
             for (const expr of clause.types) {
@@ -226,7 +206,7 @@ let ImplementsPlugin = class ImplementsPlugin extends components_1.ConverterComp
                     createLink(context, reflection, clause, expr, parentProperty, isInherit);
                     // Can't always break because we need to also set `implementationOf` if we
                     // inherit from a base class and also implement an interface.
-                    if (clause.token === ts.SyntaxKind.ImplementsKeyword) {
+                    if (clause.token === typescript_1.default.SyntaxKind.ImplementsKeyword) {
                         break out;
                     }
                 }
@@ -239,7 +219,7 @@ ImplementsPlugin = __decorate([
 ], ImplementsPlugin);
 exports.ImplementsPlugin = ImplementsPlugin;
 function constructorInheritance(context, reflection, childDecl, constructorDecl) {
-    const extendsClause = childDecl.heritageClauses?.find((cl) => cl.token === ts.SyntaxKind.ExtendsKeyword);
+    const extendsClause = childDecl.heritageClauses?.find((cl) => cl.token === typescript_1.default.SyntaxKind.ExtendsKeyword);
     if (!extendsClause)
         return;
     const name = `${extendsClause.types[0].getText()}.constructor`;
@@ -271,7 +251,7 @@ function createLink(context, reflection, clause, expr, symbol, isOverwrite) {
     function link(target) {
         if (!target)
             return;
-        if (clause.token === ts.SyntaxKind.ImplementsKeyword) {
+        if (clause.token === typescript_1.default.SyntaxKind.ImplementsKeyword) {
             target.implementationOf ?? (target.implementationOf = types_1.ReferenceType.createBrokenReference(name, project));
             return;
         }

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

@@ -38,9 +38,17 @@ let LinkResolverPlugin = class LinkResolverPlugin extends components_1.Converter
         if (project.readme) {
             project.readme = this.owner.resolveLinks(project.readme, project);
         }
-        for (const { type } of (0, reflections_1.discoverAllReferenceTypes)(project, false)) {
+        for (const { type, owner } of (0, reflections_1.discoverAllReferenceTypes)(project, false)) {
             if (!type.reflection) {
-                type.externalUrl = this.owner.resolveExternalLink(type.toDeclarationReference());
+                const resolveResult = this.owner.resolveExternalLink(type.toDeclarationReference(), owner);
+                switch (typeof resolveResult) {
+                    case "string":
+                        type.externalUrl = resolveResult;
+                        break;
+                    case "object":
+                        type.externalUrl = resolveResult.target;
+                        break;
+                }
             }
         }
     }

package/dist/lib/converter/plugins/PackagePlugin.d.ts

@@ -8,10 +8,15 @@ export declare class PackagePlugin extends ConverterComponent {
     readme: string;
     entryPointStrategy: EntryPointStrategy;
     entryPoints: string[];
+    includeVersion: boolean;
     /**
      * The file name of the found readme.md file.
      */
     private readmeFile?;
+    /**
+     * Contents of the readme.md file discovered, if any
+     */
+    private readmeContents?;
     /**
      * Contents of package.json for the active project
      */

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

@@ -31,7 +31,6 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackagePlugin = void 0;
 const Path = __importStar(require("path"));
-const FS = __importStar(require("fs"));
 const components_1 = require("../components");
 const converter_1 = require("../converter");
 const utils_1 = require("../../utils");
@@ -39,7 +38,6 @@ const fs_1 = require("../../utils/fs");
 const paths_1 = require("../../utils/paths");
 const minimalSourceFile_1 = require("../../utils/minimalSourceFile");
 const application_events_1 = require("../../application-events");
-const validation_1 = require("../../utils/validation");
 const path_1 = require("path");
 /**
  * A handler that tries to find the package.json and readme.md files of the
@@ -67,51 +65,43 @@ let PackagePlugin = class PackagePlugin extends components_1.ConverterComponent
     }
     onBegin() {
         this.readmeFile = undefined;
+        this.readmeContents = undefined;
         this.packageJson = undefined;
-        // Path will be resolved already. This is kind of ugly, but...
-        const noReadmeFile = this.readme.endsWith("none");
-        if (!noReadmeFile && this.readme) {
-            if (FS.existsSync(this.readme)) {
-                this.readmeFile = this.readme;
-            }
-        }
-        const packageAndReadmeFound = () => (noReadmeFile || this.readmeFile) && this.packageJson;
-        const reachedTopDirectory = (dirName) => dirName === Path.resolve(Path.join(dirName, ".."));
         const entryFiles = this.entryPointStrategy === utils_1.EntryPointStrategy.Packages
             ? this.entryPoints.map((d) => (0, path_1.join)(d, "package.json"))
             : this.entryPoints;
-        let dirName = Path.resolve((0, fs_1.getCommonDirectory)(entryFiles));
+        const dirName = Path.resolve((0, fs_1.getCommonDirectory)(entryFiles));
         this.application.logger.verbose(`Begin readme.md/package.json search at ${(0, paths_1.nicePath)(dirName)}`);
-        while (!packageAndReadmeFound() && !reachedTopDirectory(dirName)) {
-            FS.readdirSync(dirName).forEach((file) => {
-                const lowercaseFileName = file.toLowerCase();
-                if (!noReadmeFile &&
-                    !this.readmeFile &&
-                    lowercaseFileName === "readme.md") {
-                    this.readmeFile = Path.join(dirName, file);
-                }
-                if (!this.packageJson && lowercaseFileName === "package.json") {
-                    try {
-                        const packageJson = JSON.parse((0, utils_1.readFile)(Path.join(dirName, file)));
-                        if ((0, validation_1.validate)({ name: String, version: (0, validation_1.optional)(String) }, packageJson)) {
-                            this.packageJson = packageJson;
-                        }
-                    }
-                    catch {
-                        // Ignore
-                    }
-                }
-            });
-            dirName = Path.resolve(Path.join(dirName, ".."));
+        this.packageJson = (0, fs_1.discoverPackageJson)(dirName)?.content;
+        // Path will be resolved already. This is kind of ugly, but...
+        if (this.readme.endsWith("none")) {
+            return; // No readme, we're done
+        }
+        if (this.readme) {
+            // Readme path provided, read only that file.
+            try {
+                this.readmeContents = (0, utils_1.readFile)(this.readme);
+                this.readmeFile = this.readme;
+            }
+            catch {
+                this.application.logger.error(`Provided README path, ${(0, paths_1.nicePath)(this.readme)} could not be read.`);
+            }
+        }
+        else {
+            // No readme provided, automatically find the readme
+            const result = (0, fs_1.discoverInParentDir)("readme.md", dirName, (content) => content);
+            if (result) {
+                this.readmeFile = result.file;
+                this.readmeContents = result.content;
+            }
         }
     }
     onBeginResolve(context) {
         this.addEntries(context.project);
     }
     addEntries(project) {
-        if (this.readmeFile) {
-            const readme = (0, utils_1.readFile)(this.readmeFile);
-            const comment = this.application.converter.parseRawComment(new minimalSourceFile_1.MinimalSourceFile(readme, this.readmeFile));
+        if (this.readmeFile && this.readmeContents) {
+            const comment = this.application.converter.parseRawComment(new minimalSourceFile_1.MinimalSourceFile(this.readmeContents, this.readmeFile));
             if (comment.blockTags.length || comment.modifierTags.size) {
                 const ignored = [
                     ...comment.blockTags.map((tag) => tag.tag),
@@ -126,7 +116,9 @@ let PackagePlugin = class PackagePlugin extends components_1.ConverterComponent
             if (!project.name) {
                 project.name = project.packageName || "Documentation";
             }
-            project.packageVersion = this.packageJson.version;
+            if (this.includeVersion) {
+                project.packageVersion = this.packageJson.version;
+            }
         }
         else if (!project.name) {
             this.application.logger.warn('The --name option was not specified, and no package.json was found. Defaulting project name to "Documentation".');
@@ -143,6 +135,9 @@ __decorate([
 __decorate([
     (0, utils_1.BindOption)("entryPoints")
 ], PackagePlugin.prototype, "entryPoints", void 0);
+__decorate([
+    (0, utils_1.BindOption)("includeVersion")
+], PackagePlugin.prototype, "includeVersion", void 0);
 PackagePlugin = __decorate([
     (0, components_1.Component)({ name: "package" })
 ], PackagePlugin);