fix(docs): avoid duplicating manual documentation (#3766)

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.

this commit adds additional testing coverage to the 'docs' field of
`JsonDocsComponent`

Author: rwaskiewicz

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/markdown-overview.ts

@@ -3,7 +3,7 @@
  * @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> => {
+export const overviewToMarkdown = (overview: string | undefined): ReadonlyArray<string> => {
   if (!overview) {
     return [];
   }

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,200 @@
+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 { AUTO_GENERATE_COMMENT } from '../constants';
+import { generateDocData } from '../generate-doc-data';
+
+describe('generate-doc-data', () => {
+  describe('getDocsComponents', () => {
+    let moduleCmpWithJsdoc: d.Module;
+    let moduleCmpNoJsdoc: d.Module;
+
+    beforeEach(() => {
+      moduleCmpWithJsdoc = mockModule({
+        cmps: [
+          stubComponentCompilerMeta({
+            docs: {
+              tags: [],
+              text: 'This is the overview of `my-component`',
+            },
+          }),
+        ],
+      });
+      moduleCmpNoJsdoc = mockModule({
+        cmps: [
+          stubComponentCompilerMeta({
+            docs: {
+              tags: [],
+              text: '',
+            },
+          }),
+        ],
+      });
+    });
+
+    /**
+     * 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', moduleCmpWithJsdoc);
+        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', moduleCmpNoJsdoc);
+        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('');
+      });
+    });
+
+    describe('docs content', () => {
+      it("sets the field's contents to the jsdoc text if present", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpWithJsdoc);
+        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.docs).toBe('This is the overview of `my-component`');
+      });
+
+      it("sets the field's contents to an empty string if neither the readme, nor jsdoc are set", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
+        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.docs).toBe('');
+      });
+
+      it("sets the field's contents to an empty string if the readme doesn't contain the autogenerated comment", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        await compilerCtx.fs.writeFile('readme.md', 'this is manually generated user content');
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.docs).toBe('');
+      });
+
+      it("sets the field's contents to manually generated content when the autogenerated comment is present", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        await compilerCtx.fs.writeFile(
+          'readme.md',
+          `this is manually generated user content\n${AUTO_GENERATE_COMMENT}\nauto-generated content`
+        );
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.docs).toBe('this is manually generated user content');
+      });
+
+      it("sets the field's contents to a subset of the manually generated content", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        const readmeContent = `
+this is manually generated user content
+
+# user header
+user content
+
+# another user header
+more user content
+
+${AUTO_GENERATE_COMMENT}
+
+#some-header
+
+auto-generated content
+`;
+        await compilerCtx.fs.writeFile('readme.md', readmeContent);
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.docs).toBe('this is manually generated user content');
+      });
+
+      it("sets the field's contents to a an empty string when the manually generated content starts with a '#'", async () => {
+        const moduleMap: d.ModuleMap = new Map();
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
+        const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
+
+        const readmeContent = `
+# header that leads to skipping
+this is manually generated user content
+
+# user header
+user content
+
+# another user header
+more user content
+
+${AUTO_GENERATE_COMMENT}
+
+#some-header
+
+auto-generated content
+`;
+        await compilerCtx.fs.writeFile('readme.md', readmeContent);
+
+        const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
+
+        expect(generatedDocData.components).toHaveLength(1);
+        const componentDocData = generatedDocData.components[0];
+        expect(componentDocData.docs).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[];