diff --git a/src/compiler/docs/generate-doc-data.ts b/src/compiler/docs/generate-doc-data.ts index 0237900c35a9..25174b132e76 100644 --- a/src/compiler/docs/generate-doc-data.ts +++ b/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, diff --git a/src/compiler/docs/readme/output-docs.ts b/src/compiler/docs/readme/output-docs.ts index 34bdb0bf81f2..25e8a533474f 100644 --- a/src/compiler/docs/readme/output-docs.ts +++ b/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), diff --git a/src/compiler/docs/test/generate-doc-data.spec.ts b/src/compiler/docs/test/generate-doc-data.spec.ts new file mode 100644 index 000000000000..f28f99bb9bc4 --- /dev/null +++ b/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(''); + }); + }); + }); +}); diff --git a/src/declarations/stencil-public-docs.ts b/src/declarations/stencil-public-docs.ts index 1fd254cdc680..18b6a795fa17 100644 --- a/src/declarations/stencil-public-docs.ts +++ b/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[];