From b842baa47e543ad3cd38231d1dc525726d883ba7 Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Sat, 21 Jul 2018 16:13:00 +0200 Subject: [PATCH] docs: properly show method overloads * Shows method overloads in the documentation instead of showing the overload-base method that has most likely no `JSDoc` nor good-explaining parameter names (parameters have multiple purposes and types) --- tools/dgeni/processors/categorizer.ts | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/tools/dgeni/processors/categorizer.ts b/tools/dgeni/processors/categorizer.ts index 6df412f19f23..4554988bcc5c 100644 --- a/tools/dgeni/processors/categorizer.ts +++ b/tools/dgeni/processors/categorizer.ts @@ -49,6 +49,7 @@ export class Categorizer implements Processor { // Special decorations for real class documents that don't apply for interfaces. if (classLikeDoc.docType === 'class') { this.decorateClassDoc(classLikeDoc as CategorizedClassDoc); + this.replaceMethodsWithOverload(classLikeDoc as CategorizedClassDoc); } // Call decorate hooks that can modify the method and property docs. @@ -117,6 +118,29 @@ export class Categorizer implements Processor { propertyDoc.isDirectiveOutput = !!outputMetadata; propertyDoc.directiveOutputAlias = (outputMetadata && outputMetadata.alias) || ''; } + + /** + * Walks through every method of the specified class doc and replaces the method + * with its referenced overload method definitions, if the method is having overload definitions. + */ + private replaceMethodsWithOverload(classDoc: CategorizedClassDoc) { + const methodsToAdd: CategorizedMethodMemberDoc[] = []; + + classDoc.methods.forEach((methodDoc, index) => { + if (methodDoc.overloads.length > 0) { + + // Add each method overload to the methods that will be shown in the docs. + // Note that we cannot add the overloads immediately to the methods array because + // that would cause the iteration to visit the new overloads. + methodsToAdd.push(...methodDoc.overloads as CategorizedMethodMemberDoc[]); + + // Remove the base method for the overloads from the documentation. + classDoc.methods.splice(index, 1); + } + }); + + classDoc.methods.push(...methodsToAdd); + } } /** Filters any duplicate classDoc members from an array */