build: set @returns description for void async methods automatically (#17751)

Automatically sets the `@returns` tag description for asynchronous
methods which do not return any value.

This is a proposal based on the commit in:
#17723 (comment)

Author: devversion

tools/dgeni/docs-package.ts

@@ -2,6 +2,7 @@ import {Package} from 'dgeni';
 import {Host} from 'dgeni-packages/typescript/services/ts-host/host';
 import {HighlightNunjucksExtension} from './nunjucks-tags/highlight';
 import {patchLogService} from './patch-log-service';
+import {AsyncReturnDescriptionProcessor} from './processors/async-return-description';
 import {DocsPrivateFilter} from './processors/docs-private-filter';
 import {Categorizer} from './processors/categorizer';
 import {FilterDuplicateExports} from './processors/filter-duplicate-exports';
@@ -49,14 +50,17 @@ apiDocsPackage.processor(new Categorizer());
 // Processor to group docs into top-level entry-points such as "tabs", "sidenav", etc.
 apiDocsPackage.processor(new EntryPointGrouper());
 
+// Processor that automatically adds a return description for async methods.
+apiDocsPackage.processor(new AsyncReturnDescriptionProcessor());
+
 // Configure the log level of the API docs dgeni package.
 apiDocsPackage.config(function(log: any) {
   return log.level = 'warning';
 });
 
 // Configure the processor for reading files from the file system.
 apiDocsPackage.config(function(readFilesProcessor: any) {
-  // Disable we currently only use the "readTypeScriptModules" processor
+  // Disabled since we only use the "readTypeScriptModules" processor
   readFilesProcessor.$enabled = false;
 });
 

tools/dgeni/processors/async-return-description.ts

@@ -0,0 +1,54 @@
+import {DocCollection, Processor} from 'dgeni';
+import {ApiDoc} from 'dgeni-packages/typescript/api-doc-types/ApiDoc';
+import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
+import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
+import * as ts from 'typescript';
+
+/** Type describing a function-like API doc (i.e. a function, or a class method member). */
+type FunctionLikeDoc = (FunctionExportDoc|MethodMemberDoc) & {returns?: {description: string}};
+
+/**
+ * Processor that automatically sets the @return description for
+ * asynchronous methods which do not return any value.
+ */
+export class AsyncReturnDescriptionProcessor implements Processor {
+  name = 'async-return-description';
+  $runBefore = ['categorizer'];
+
+  $process(docs: DocCollection) {
+    docs.forEach((doc: ApiDoc) => {
+      if (!isFunctionLikeDoc(doc)) {
+        return;
+      }
+      const typeString = getTypeOfFunctionLikeDoc(doc);
+      if (!doc.returns && typeString === 'Promise<void>') {
+        doc.returns = {description: 'Promise that resolves when the action completes.'};
+      }
+    });
+  }
+}
+
+/**
+ * Gets the type of the function-like doc. If no explicit type has been specified,
+ * the type checker is used to compute a type string based on the function body.
+ */
+function getTypeOfFunctionLikeDoc(doc: FunctionLikeDoc): string|null {
+  if (doc.type) {
+    return doc.type;
+  }
+
+  const decl = doc.declaration as ts.MethodDeclaration|ts.FunctionDeclaration;
+  const signature = doc.typeChecker.getSignatureFromDeclaration(decl);
+
+  if (!signature) {
+    return null;
+  }
+
+  const returnType = doc.typeChecker.getReturnTypeOfSignature(signature);
+  return doc.typeChecker.typeToString(returnType);
+}
+
+/** Whether the given API doc is a function-like doc. */
+function isFunctionLikeDoc(doc: ApiDoc): doc is FunctionLikeDoc {
+  return doc instanceof FunctionExportDoc || doc instanceof MethodMemberDoc;
+}

tools/dgeni/processors/categorizer.ts

@@ -36,7 +36,7 @@ import {sortCategorizedMethodMembers, sortCategorizedPropertyMembers} from '../c
  */
 export class Categorizer implements Processor {
   name = 'categorizer';
-  $runBefore = ['docs-processed'];
+  $runBefore = ['docs-processed', 'entryPointGrouper'];
 
   $process(docs: DocCollection) {
     docs.filter(doc => doc.docType === 'class' || doc.docType === 'interface')