From 7a649f0e4df5ee83ee14a38e056592166c0253da Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@abv.bg>
Date: Mon, 24 May 2021 16:55:37 +0200
Subject: [PATCH] docs: incorrect descriptions for inherited class members

In #22482 some changes were made that switched the doc rendering from `description` to `content` in an attempt to expose the descriptions for inherited class members. It turns out that `content` is actually the description of the member including `@param` and `@returns` tags which we don't want to show either.

After some investigation, it turns out that the root cause of the descriptions not being shown is that dgeni won't assign a `description` if the base class isn't exported.

These changes resolve the issue by falling back to `content` if there is no `description` and stripping out the JSDoc tags from it manually.
---
 tools/dgeni/common/dgeni-definitions.ts              |  1 +
 tools/dgeni/processors/merge-inherited-properties.ts | 12 ++++++++++++
 tools/dgeni/templates/method.template.html           |  4 ++--
 tools/dgeni/templates/property.template.html         |  2 +-
 4 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/tools/dgeni/common/dgeni-definitions.ts b/tools/dgeni/common/dgeni-definitions.ts
index d8e0884e4d93..1009b7e2a2bc 100644
--- a/tools/dgeni/common/dgeni-definitions.ts
+++ b/tools/dgeni/common/dgeni-definitions.ts
@@ -40,6 +40,7 @@ export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLik
 
 /** Extended Dgeni property-member document that includes extracted Angular metadata. */
 export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc, DeprecationInfo {
+  description: string;
   isDirectiveInput: boolean;
   isDirectiveOutput: boolean;
   directiveInputAlias: string;
diff --git a/tools/dgeni/processors/merge-inherited-properties.ts b/tools/dgeni/processors/merge-inherited-properties.ts
index e0ab4d13a21a..7b9ef4078e7c 100644
--- a/tools/dgeni/processors/merge-inherited-properties.ts
+++ b/tools/dgeni/processors/merge-inherited-properties.ts
@@ -52,8 +52,20 @@ export class MergeInheritedProperties implements Processor {
       // by using an instance comparison.
       // tslint:disable-next-line:ban Need to use Object.assign to preserve the prototype.
       const newMemberDoc = Object.assign(Object.create(memberDoc), memberDoc);
+
+      // Dgeni won't add the `description` if the member doc belongs to a class
+      // that isn't exported. If that's the case, we fall back to assigning it
+      // ourselves by stripping JSDoc tags from the raw description.
+      // TODO: figure out a more robust solution that will ensure that the description is
+      // always added.
+      newMemberDoc.description = newMemberDoc.description || stripJsDocTags(memberDoc.content);
       newMemberDoc.containerDoc = destination;
       destination.members.push(newMemberDoc);
     }
   }
 }
+
+/** Strips all of the content after the first JSDoc tag from a string. */
+function stripJsDocTags(text: string): string {
+  return text.split(/\s@[a-zA-Z-]*\s/)[0];
+}
diff --git a/tools/dgeni/templates/method.template.html b/tools/dgeni/templates/method.template.html
index cd2a9667f287..54f77f8ed7cb 100644
--- a/tools/dgeni/templates/method.template.html
+++ b/tools/dgeni/templates/method.template.html
@@ -18,10 +18,10 @@
       </th>
     </tr>
   </thead>
-  {%- if method.content -%}
+  {%- if method.description -%}
   <tr class="docs-api-method-description-row">
     <td colspan="2" class="docs-api-method-description-cell">
-      {$ method.content | marked | safe $}
+      {$ method.description | marked | safe $}
     </td>
   </tr>
   {%- endif -%}
diff --git a/tools/dgeni/templates/property.template.html b/tools/dgeni/templates/property.template.html
index d205b7ab7b28..c56b2e2d4c45 100644
--- a/tools/dgeni/templates/property.template.html
+++ b/tools/dgeni/templates/property.template.html
@@ -30,5 +30,5 @@
       <code>{$ property.name $}: {$ property.type $}</code>
     </p>
   </td>
-  <td class="docs-api-property-description">{$ property.content | marked | safe $}</td>
+  <td class="docs-api-property-description">{$ property.description | marked | safe $}</td>
 </tr>