fix(docs): avoid duplicating manual documentation

this commit fixes a regression that was introduced in 2db4f4d
(#3635). the original commit did not take into account the fact that a
user could have manually written text in their component's markdown
file. that content would be assigned to the value used to generated the
markdown file's "Overview" section, causing the content to be displayed
twice.

the contents of the `docs` field (i.e. the way that value is generated).
cannot be changed, as `JsonDocs` publicly exposes that field (via a
`JsonDocsComponent` value), and may be used by custom documentation
generators.

instead, this commit adds an optional 'overview' field to the
`JsonDocsComponent` type. the intent here is to avoid _most_
assignability errors by making this field optional. the value is
assigned when stencil generates its documentation data with the text
from the class component's jsdoc.

src/compiler/docs/generate-doc-data.ts

@@ -60,6 +60,7 @@ const getDocsComponents = async (
           usagesDir,
           tag: cmp.tagName,
           readme,
+          overview: cmp.docs.text,
           usage,
           docs: generateDocs(readme, cmp.docs),
           docsTags: cmp.docs.tags,

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

@@ -55,7 +55,7 @@ export const generateMarkdown = (
     '',
     '',
     ...getDocsDeprecation(cmp),
-    ...overviewToMarkdown(cmp.docs),
+    ...overviewToMarkdown(cmp.overview),
     ...usageToMarkdown(cmp.usage),
     ...propsToMarkdown(cmp.props),
     ...eventsToMarkdown(cmp.events),

src/compiler/docs/test/generate-doc-data.spec.ts

@@ -0,0 +1,81 @@
+import { mockBuildCtx, mockCompilerCtx, mockModule, mockValidatedConfig } from '@stencil/core/testing';
+
+import type * as d from '../../../declarations';
+import { getComponentsFromModules } from '../../output-targets/output-utils';
+import { stubComponentCompilerMeta } from '../../types/tests/ComponentCompilerMeta.stub';
+import { generateDocData } from '../generate-doc-data';
+
+describe('generate-doc-data', () => {
+  describe('getDocsComponents', () => {
+    /**
+     * Setup function for the {@link generateDocData} function exported by the module under test
+     * @param moduleMap a map of {@link d.ModuleMap} entities to add to the returned compiler and build contexts
+     * @returns the arguments required to invoke the method under test
+     */
+    const setup = (
+      moduleMap: d.ModuleMap
+    ): { validatedConfig: d.ValidatedConfig; compilerCtx: d.CompilerCtx; buildCtx: d.BuildCtx } => {
+      const validatedConfig: d.ValidatedConfig = mockValidatedConfig();
+
+      const compilerCtx: d.CompilerCtx = mockCompilerCtx(validatedConfig);
+      compilerCtx.moduleMap = moduleMap;
+
+      const modules = Array.from(compilerCtx.moduleMap.values());
+      const buildCtx: d.BuildCtx = mockBuildCtx(validatedConfig, compilerCtx);
+      buildCtx.moduleFiles = modules;
+      buildCtx.components = getComponentsFromModules(modules);
+
+      return { validatedConfig, compilerCtx, buildCtx };
+    };
+
+    describe('component JSDoc overview', () => {
+      it("takes the value from the component's JSDoc", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set(
+          'path/to/component.tsx',
+          mockModule({
+            cmps: [
+              stubComponentCompilerMeta({
+                docs: {
+                  tags: [],
+                  text: 'This is the overview of `my-component`',
+                },
+              }),
+            ],
+          })
+        );
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.overview).toBe('This is the overview of `my-component`');
+      });
+
+      it('sets the value to the empty string when there is no JSDoc', async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set(
+          'path/to/component.tsx',
+          mockModule({
+            cmps: [
+              stubComponentCompilerMeta({
+                docs: {
+                  tags: [],
+                  text: '',
+                },
+              }),
+            ],
+          })
+        );
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.overview).toBe('');
+      });
+    });
+  });
+});

src/declarations/stencil-public-docs.ts

@@ -19,6 +19,10 @@ export interface JsonDocsComponent {
   readme: string;
   docs: string;
   docsTags: JsonDocsTag[];
+  /**
+   * The comment found at in a class-level JSDoc for a Stencil component.
+   */
+  overview?: string;
   usage: JsonDocsUsage;
   props: JsonDocsProp[];
   methods: JsonDocsMethod[];