From c77e0acf01cd6cdd491e9adfbf8737a7c4370dbe Mon Sep 17 00:00:00 2001 From: Alice Pote Date: Tue, 6 Dec 2022 13:57:59 -0500 Subject: [PATCH 1/4] chore(util): update list of suppressed JSDoc tags to align with Framework When #3525 merged it contained a list of JSDoc tags which should be suppressed from component-level generated documentation in typedef files. This commit updates that list to add some tags that Framework would not like to have show up all over the place. --- src/utils/util.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/utils/util.ts b/src/utils/util.ts index 24b4c7bdc68..7a810a20d95 100644 --- a/src/utils/util.ts +++ b/src/utils/util.ts @@ -2,7 +2,7 @@ import type * as d from '../declarations'; import { dashToPascalCase, isString, toDashCase } from './helpers'; import { buildError } from './message-utils'; -const SUPPRESSED_JSDOC_TAGS: string[] = ['internal']; +const SUPPRESSED_JSDOC_TAGS: ReadonlyArray = ['virtualProp', 'slot', 'part', 'internal']; /** * Create a stylistically-appropriate JS variable name from a filename From 2028dcda5f0a932569755412878678a88cc13352 Mon Sep 17 00:00:00 2001 From: Alice Pote Date: Tue, 6 Dec 2022 14:40:13 -0500 Subject: [PATCH 2/4] changes to test files b/c of SUPPRESSED_JSDOC_TAGS change --- test/end-to-end/src/components.d.ts | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/test/end-to-end/src/components.d.ts b/test/end-to-end/src/components.d.ts index 6852676297b..c6eaaa8019f 100644 --- a/test/end-to-end/src/components.d.ts +++ b/test/end-to-end/src/components.d.ts @@ -16,8 +16,6 @@ export namespace Components { } /** * Component that helps display a list of cars - * @slot header - The slot for the header content. - * @part car - The shadow part to target to style the car. */ interface CarList { "cars": CarData[]; @@ -52,9 +50,6 @@ export namespace Components { } interface PrerenderCmp { } - /** - * @virtualProp mode - Mode - */ interface PropCmp { "first": string; "lastName": string; @@ -102,8 +97,6 @@ declare global { }; /** * Component that helps display a list of cars - * @slot header - The slot for the header content. - * @part car - The shadow part to target to style the car. */ interface HTMLCarListElement extends Components.CarList, HTMLStencilElement { } @@ -177,9 +170,6 @@ declare global { prototype: HTMLPrerenderCmpElement; new (): HTMLPrerenderCmpElement; }; - /** - * @virtualProp mode - Mode - */ interface HTMLPropCmpElement extends Components.PropCmp, HTMLStencilElement { } var HTMLPropCmpElement: { @@ -243,8 +233,6 @@ declare namespace LocalJSX { } /** * Component that helps display a list of cars - * @slot header - The slot for the header content. - * @part car - The shadow part to target to style the car. */ interface CarList { "cars"?: CarData[]; @@ -278,9 +266,6 @@ declare namespace LocalJSX { } interface PrerenderCmp { } - /** - * @virtualProp mode - Mode - */ interface PropCmp { "first"?: string; "lastName"?: string; @@ -330,8 +315,6 @@ declare module "@stencil/core" { "car-detail": LocalJSX.CarDetail & JSXBase.HTMLAttributes; /** * Component that helps display a list of cars - * @slot header - The slot for the header content. - * @part car - The shadow part to target to style the car. */ "car-list": LocalJSX.CarList & JSXBase.HTMLAttributes; "dom-api": LocalJSX.DomApi & JSXBase.HTMLAttributes; @@ -345,9 +328,6 @@ declare module "@stencil/core" { "method-cmp": LocalJSX.MethodCmp & JSXBase.HTMLAttributes; "path-alias-cmp": LocalJSX.PathAliasCmp & JSXBase.HTMLAttributes; "prerender-cmp": LocalJSX.PrerenderCmp & JSXBase.HTMLAttributes; - /** - * @virtualProp mode - Mode - */ "prop-cmp": LocalJSX.PropCmp & JSXBase.HTMLAttributes; "slot-cmp": LocalJSX.SlotCmp & JSXBase.HTMLAttributes; "slot-cmp-container": LocalJSX.SlotCmpContainer & JSXBase.HTMLAttributes; From f8a173a7e3f023b3e02153901684bf82cd57b9b9 Mon Sep 17 00:00:00 2001 From: Alice Pote Date: Tue, 6 Dec 2022 14:40:28 -0500 Subject: [PATCH 3/4] comments --- src/utils/util.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/utils/util.ts b/src/utils/util.ts index 7a810a20d95..ef6be3a7ea5 100644 --- a/src/utils/util.ts +++ b/src/utils/util.ts @@ -2,6 +2,10 @@ import type * as d from '../declarations'; import { dashToPascalCase, isString, toDashCase } from './helpers'; import { buildError } from './message-utils'; +/** + * A set of JSDoc tags which should be excluded from JSDoc comments + * included in output typedefs. + */ const SUPPRESSED_JSDOC_TAGS: ReadonlyArray = ['virtualProp', 'slot', 'part', 'internal']; /** @@ -117,7 +121,8 @@ function formatDocBlock(docs: d.CompilerJsDoc, indentation: number = 0): string } /** - * Get all lines part of the doc block + * Get all lines which are part of the doc block + * * @param docs the compiled JS docs * @returns list of lines part of the doc block */ From b1bbff7b06a9d120c586ea21f2426eeca714c5aa Mon Sep 17 00:00:00 2001 From: Alice Pote Date: Tue, 6 Dec 2022 16:26:45 -0500 Subject: [PATCH 4/4] changes to make BS tests pass --- test/karma/test-app/components.d.ts | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/test/karma/test-app/components.d.ts b/test/karma/test-app/components.d.ts index 0ea66ad381c..d9b069a775a 100644 --- a/test/karma/test-app/components.d.ts +++ b/test/karma/test-app/components.d.ts @@ -226,9 +226,6 @@ export namespace Components { } interface ShadowDomBasicRoot { } - /** - * @virtualProp {string} colormode - The mode determines which platform styles to use. - */ interface ShadowDomMode { /** * The mode determines which platform styles to use. @@ -871,9 +868,6 @@ declare global { prototype: HTMLShadowDomBasicRootElement; new (): HTMLShadowDomBasicRootElement; }; - /** - * @virtualProp {string} colormode - The mode determines which platform styles to use. - */ interface HTMLShadowDomModeElement extends Components.ShadowDomMode, HTMLStencilElement { } var HTMLShadowDomModeElement: { @@ -1496,9 +1490,6 @@ declare namespace LocalJSX { } interface ShadowDomBasicRoot { } - /** - * @virtualProp {string} colormode - The mode determines which platform styles to use. - */ interface ShadowDomMode { /** * The mode determines which platform styles to use. @@ -1822,9 +1813,6 @@ declare module "@stencil/core" { "shadow-dom-array-root": LocalJSX.ShadowDomArrayRoot & JSXBase.HTMLAttributes; "shadow-dom-basic": LocalJSX.ShadowDomBasic & JSXBase.HTMLAttributes; "shadow-dom-basic-root": LocalJSX.ShadowDomBasicRoot & JSXBase.HTMLAttributes; - /** - * @virtualProp {string} colormode - The mode determines which platform styles to use. - */ "shadow-dom-mode": LocalJSX.ShadowDomMode & JSXBase.HTMLAttributes; "shadow-dom-mode-root": LocalJSX.ShadowDomModeRoot & JSXBase.HTMLAttributes; "shadow-dom-slot-basic": LocalJSX.ShadowDomSlotBasic & JSXBase.HTMLAttributes;