test(docs-gen): add additional tests for doc generation

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

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

@@ -3,10 +3,37 @@ import { mockBuildCtx, mockCompilerCtx, mockModule, mockValidatedConfig } from '
 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
@@ -31,19 +58,7 @@ describe('generate-doc-data', () => {
     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`',
-                },
-              }),
-            ],
-          })
-        );
+        moduleMap.set('path/to/component.tsx', moduleCmpWithJsdoc);
         const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
 
         const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
@@ -55,19 +70,7 @@ describe('generate-doc-data', () => {
 
       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: '',
-                },
-              }),
-            ],
-          })
-        );
+        moduleMap.set('path/to/component.tsx', moduleCmpNoJsdoc);
         const { validatedConfig, compilerCtx, buildCtx } = setup(moduleMap);
 
         const generatedDocData = await generateDocData(validatedConfig, compilerCtx, buildCtx);
@@ -77,5 +80,121 @@ describe('generate-doc-data', () => {
         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('');
+      });
+    });
   });
 });