docs: incorrect descriptions for inherited class members (#22766)

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.

Author: crisbeto

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;

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];
+}

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 -%}

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>