diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a309cb5a..7e3b57557 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ - TypeDoc will now treat `@typedef {import("foo").Bar} Baz` type declarations which forward type parameters to the imported symbol as re-exports of that symbol, #2044. +### Bug Fixes + +- TypeDoc will now prefer comments on variable declarations over signature comments, #2042. + ## v0.23.14 (2022-09-03) ### Features diff --git a/src/lib/converter/factories/signature.ts b/src/lib/converter/factories/signature.ts index 2b6709182..007bd6da4 100644 --- a/src/lib/converter/factories/signature.ts +++ b/src/lib/converter/factories/signature.ts @@ -1,6 +1,7 @@ import * as ts from "typescript"; import * as assert from "assert"; import { + ConversionFlags, DeclarationReflection, IntrinsicType, ParameterReflection, @@ -41,7 +42,15 @@ export function createSignature( kind, context.scope ); - if (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 + // will copy the comment down if this signature doesn't have one, so don't set one. + if ( + declaration && + (!context.scope.comment || + !(context.scope.conversionFlags & ConversionFlags.VariableSource)) + ) { sigRef.comment = getSignatureComment( declaration, context.converter.config, diff --git a/src/lib/converter/symbols.ts b/src/lib/converter/symbols.ts index 75939ae9f..781e36e62 100644 --- a/src/lib/converter/symbols.ts +++ b/src/lib/converter/symbols.ts @@ -8,6 +8,7 @@ import { Reflection, ReflectionFlag, ReflectionKind, + ConversionFlags, } from "../models"; import { getEnumFlags, @@ -894,7 +895,7 @@ function convertVariableAsFunction( exportSymbol ); setModifiers(symbol, accessDeclaration, reflection); - + reflection.conversionFlags |= ConversionFlags.VariableSource; context.finalizeDeclarationReflection(reflection); const reflectionContext = context.withScope(reflection); diff --git a/src/lib/models/reflections/declaration.ts b/src/lib/models/reflections/declaration.ts index 9c0db2b0f..4ab0f12cd 100644 --- a/src/lib/models/reflections/declaration.ts +++ b/src/lib/models/reflections/declaration.ts @@ -29,6 +29,14 @@ export interface DeclarationHierarchy { isTarget?: boolean; } +/** + * @internal + */ +export enum ConversionFlags { + None = 0, + VariableSource = 1, +} + /** * A reflection that represents a single declaration emitted by the TypeScript compiler. * @@ -140,6 +148,12 @@ export class DeclarationReflection extends ContainerReflection { */ version?: string; + /** + * Flags for information about a reflection which is needed solely during conversion. + * @internal + */ + conversionFlags = ConversionFlags.None; + override hasGetterOrSetter(): boolean { return !!this.getSignature || !!this.setSignature; } diff --git a/src/lib/models/reflections/index.ts b/src/lib/models/reflections/index.ts index 6a5ef9dad..a85c09024 100644 --- a/src/lib/models/reflections/index.ts +++ b/src/lib/models/reflections/index.ts @@ -6,7 +6,7 @@ export { } from "./abstract"; export type { TraverseCallback } from "./abstract"; export { ContainerReflection } from "./container"; -export { DeclarationReflection } from "./declaration"; +export { DeclarationReflection, ConversionFlags } from "./declaration"; export type { DeclarationHierarchy } from "./declaration"; export { ReflectionKind } from "./kind"; export { ParameterReflection } from "./parameter"; diff --git a/src/test/converter2/issues/gh2042.ts b/src/test/converter2/issues/gh2042.ts new file mode 100644 index 000000000..ba1ebf7e7 --- /dev/null +++ b/src/test/converter2/issues/gh2042.ts @@ -0,0 +1,23 @@ +function factory() { + /** inner docs */ + function fn() {} + return fn; +} + +export const built = factory(); + +/** outer docs */ +export const built2 = factory(); + +const obj = { + /** inner docs */ + fn(x: unknown) {}, +}; + +export const fn = obj.fn; + +/** + * outer docs + * @param x param-docs + */ +export const fn2 = obj.fn; diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts index da18d79ac..b6dc2996c 100644 --- a/src/test/issueTests.ts +++ b/src/test/issueTests.ts @@ -768,6 +768,25 @@ export const issueTests: { equal(AnotherCtor.type.declaration.signatures?.length, 1); }, + gh2042(project) { + for (const [name, docs] of [ + ["built", "inner docs"], + ["built2", "outer docs"], + ["fn", "inner docs"], + ["fn2", "outer docs"], + ]) { + const refl = query(project, name); + ok(refl.signatures?.[0]); + equal( + Comment.combineDisplayParts( + refl.signatures[0].comment?.summary + ), + docs, + name + ); + } + }, + gh2044(project) { for (const [name, ref] of [ ["Foo", false],