feat(docs-readme): add overview to readme

this commit adds an 'Overview' section to the generated `README.md` file
for a component. this implementation is simple (and arguably naive)
intentionally. there is quite a bit that folks could do in the context
of a JSDoc. rather than attempting to capture every use case and
potentially overcomplicate our solution, we start simple and can iterate
from there.

src/compiler/docs/readme/markdown-overview.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate an 'Overview' section for a markdown file
+ * @param overview a component-level comment string to place in a markdown file
+ * @returns The generated Overview section. If the provided overview is empty, return an empty list
+ */
+export const overviewToMarkdown = (overview: string): ReadonlyArray<string> => {
+  if (!overview) {
+    return [];
+  }
+
+  const content: string[] = [];
+  content.push(`## Overview`);
+  content.push('');
+  content.push(`${overview.trim()}`);
+  content.push('');
+
+  return content;
+};

src/compiler/docs/readme/output-docs.ts

@@ -6,6 +6,7 @@ import { stylesToMarkdown } from './markdown-css-props';
 import { depsToMarkdown } from './markdown-dependencies';
 import { eventsToMarkdown } from './markdown-events';
 import { methodsToMarkdown } from './markdown-methods';
+import { overviewToMarkdown } from './markdown-overview';
 import { partsToMarkdown } from './markdown-parts';
 import { propsToMarkdown } from './markdown-props';
 import { slotsToMarkdown } from './markdown-slots';
@@ -54,6 +55,7 @@ export const generateMarkdown = (
     '',
     '',
     ...getDocsDeprecation(cmp),
+    ...overviewToMarkdown(cmp.docs),
     ...usageToMarkdown(cmp.usage),
     ...propsToMarkdown(cmp.props),
     ...eventsToMarkdown(cmp.events),

src/compiler/docs/test/markdown-overview.spec.ts

@@ -0,0 +1,50 @@
+import { overviewToMarkdown } from '../readme/markdown-overview';
+
+describe('markdown-overview', () => {
+  describe('overviewToMarkdown', () => {
+    it('returns an empty string if no docs exist on the component', () => {
+      const generatedOverview = overviewToMarkdown('').join('\n');
+
+      expect(generatedOverview).toBe('');
+    });
+
+    it('generates a single line overview', () => {
+      const generatedOverview = overviewToMarkdown('This is a custom button component').join('\n');
+
+      expect(generatedOverview).toBe(`## Overview
+
+This is a custom button component
+`);
+    });
+
+    it('generates a multi-line overview', () => {
+      const description = `This is a custom button component.
+It is to be used throughout the design system.
+
+This is a comment followed by an extra newline.
+`;
+      const generatedOverview = overviewToMarkdown(description).join('\n');
+
+      expect(generatedOverview).toBe(`## Overview
+
+This is a custom button component.
+It is to be used throughout the design system.
+
+This is a comment followed by an extra newline.
+`);
+    });
+
+    it('trims leading & trailing newlines single lines', () => {
+      const description = `
+This is a custom button component.
+
+`;
+      const generatedOverview = overviewToMarkdown(description).join('\n');
+
+      expect(generatedOverview).toBe(`## Overview
+
+This is a custom button component.
+`);
+    });
+  });
+});