build(aio): split the description property in API docs (#22401)

* The first paragraph is now split off into the `shortDescription` property.
* Usage of `howToUse` and `whatItDoes` have been updated.
* The "Overview" heading for class is removed as it is self-evident
* The original horizontal rule styling below the main heading is removed as not part of the new design

Closes #22385

PR Close #22401

aio/tools/transforms/angular-api-package/processors/splitDescription.js

@@ -0,0 +1,28 @@
+/**
+ * Split the descripton (of selected docs) into:
+ * * `shortDescription`: the first paragraph
+ * * `description`: the rest of the paragraphs
+ */
+module.exports = function splitDescription() {
+  return {
+    $runAfter: ['tags-extracted', 'migrateLegacyJSDocTags'],
+    $runBefore: ['processing-docs'],
+    docTypes: [],
+    $process(docs) {
+      docs.forEach(doc => {
+        if (this.docTypes.indexOf(doc.docType) !== -1 && doc.description !== undefined) {
+          const description = doc.description.trim();
+          const endOfParagraph = description.search(/\n\s*\n/);
+          if (endOfParagraph === -1) {
+            doc.shortDescription = description;
+            doc.description = '';
+          } else {
+            doc.shortDescription = description.substr(0, endOfParagraph).trim();
+            doc.description = description.substr(endOfParagraph).trim();
+          }
+        }
+      });
+    }
+  };
+};
+