diff --git a/CHANGELOG.md b/CHANGELOG.md index 5edef3908..454023f25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ - Fix crash when converting `export default undefined`, #2175. - Fix error in console when clicking on headings in the readme, #2170. +- TypeDoc will now ignore parameters of callback parameters when validating that all parameters have documentation, #2154. ### Thanks! diff --git a/src/lib/validation/documentation.ts b/src/lib/validation/documentation.ts index 767a1fffb..29693a543 100644 --- a/src/lib/validation/documentation.ts +++ b/src/lib/validation/documentation.ts @@ -1,5 +1,6 @@ import { DeclarationReflection, + ParameterReflection, ProjectReflection, Reflection, ReflectionKind, @@ -38,11 +39,24 @@ export function validateDocumentation( const toProcess = project.getReflectionsByKind(kinds); const seen = new Set(); - while (toProcess.length) { + outer: while (toProcess.length) { const ref = toProcess.shift()!; if (seen.has(ref)) continue; seen.add(ref); + // If there is a parameter inside another parameter, this is probably a callback function. + // TypeDoc doesn't support adding comments with @param to nested parameters, so it seems + // silly to warn about these. + if (ref.kindOf(ReflectionKind.Parameter)) { + let r: Reflection | undefined = ref.parent; + while (r) { + if (r.kindOf(ReflectionKind.Parameter)) { + continue outer; + } + r = r.parent; + } + } + if (ref instanceof DeclarationReflection) { const signatures = ref.type instanceof ReflectionType diff --git a/src/test/converter2/validation/callbackParameters.ts b/src/test/converter2/validation/callbackParameters.ts new file mode 100644 index 000000000..129973a76 --- /dev/null +++ b/src/test/converter2/validation/callbackParameters.ts @@ -0,0 +1,20 @@ +/** + * Test case from https://github.com/TypeStrong/typedoc/issues/2154 + * @param data The data object to add equality to + * @param equals The equality function + * @param hashCode The hash code function + */ +export function gh2154( + data: unknown, + equals: (a: 1, b: 2) => boolean, + hashCode: (data: 3) => number +) {} + +export class AnotherTest { + /** + * Property is documented + * @param a test + * @param b another + */ + equals!: (a: 1, b: 2) => boolean; +} diff --git a/src/test/validation.test.ts b/src/test/validation.test.ts index 09c8a9d94..ff8d27303 100644 --- a/src/test/validation.test.ts +++ b/src/test/validation.test.ts @@ -206,4 +206,12 @@ describe("validateDocumentation", () => { ); logger.expectNoOtherMessages(); }); + + it("Should correctly handle callback parameters", () => { + const project = convertValidationFile("callbackParameters.ts"); + const logger = new TestLogger(); + validateDocumentation(project, logger, ["Parameter", "Property"]); + + logger.expectNoOtherMessages(); + }); });