diff --git a/packages/kbn-docs-utils/scripts/update_fixture_comments.js b/packages/kbn-docs-utils/scripts/update_fixture_comments.js index aadb3c1aafd61..03d259762b052 100644 --- a/packages/kbn-docs-utils/scripts/update_fixture_comments.js +++ b/packages/kbn-docs-utils/scripts/update_fixture_comments.js @@ -13,6 +13,7 @@ const path = require('node:path'); const categories = [ { key: 'missingComments', title: 'missing comments' }, { key: 'paramDocMismatches', title: 'param doc mismatches' }, + { key: 'missingComplexTypeInfo', title: 'missing complex type info' }, { key: 'isAnyType', title: 'any usage' }, { key: 'noReferences', title: 'no references' }, ]; diff --git a/packages/kbn-docs-utils/src/__test_helpers__/mocks.ts b/packages/kbn-docs-utils/src/__test_helpers__/mocks.ts index c989b1f6ac0ce..eb70ee3430836 100644 --- a/packages/kbn-docs-utils/src/__test_helpers__/mocks.ts +++ b/packages/kbn-docs-utils/src/__test_helpers__/mocks.ts @@ -66,6 +66,7 @@ export const createMockPluginStats = (overrides: Partial = {}): ApiSta isAnyType: [], noReferences: [], paramDocMismatches: [], + missingComplexTypeInfo: [], missingExports: 0, deprecatedAPIsReferencedCount: 0, unreferencedDeprecatedApisCount: 0, @@ -97,6 +98,7 @@ export const createMockPluginMetaInfo = ( isAnyType: [], noReferences: [], paramDocMismatches: [], + missingComplexTypeInfo: [], missingExports: 0, deprecatedAPIsReferencedCount: 0, unreferencedDeprecatedApisCount: 0, diff --git a/packages/kbn-docs-utils/src/check_package_docs_cli.test.ts b/packages/kbn-docs-utils/src/check_package_docs_cli.test.ts index 9c75b87c0252c..d5f83fc2c8a9d 100644 --- a/packages/kbn-docs-utils/src/check_package_docs_cli.test.ts +++ b/packages/kbn-docs-utils/src/check_package_docs_cli.test.ts @@ -40,6 +40,7 @@ const createPlugin = (id: string, isPlugin = true): PluginOrPackage => ({ const createBaseStats = (pluginId: string): AllPluginStats => ({ [pluginId]: { missingComments: [], + missingComplexTypeInfo: [], isAnyType: [], noReferences: [], paramDocMismatches: [], diff --git a/packages/kbn-docs-utils/src/check_package_docs_cli.ts b/packages/kbn-docs-utils/src/check_package_docs_cli.ts index ace0049377208..16172b4a218af 100644 --- a/packages/kbn-docs-utils/src/check_package_docs_cli.ts +++ b/packages/kbn-docs-utils/src/check_package_docs_cli.ts @@ -85,7 +85,9 @@ export const getValidationResults = ( const hasAnyIssues = shouldCheckAny && pluginStats.isAnyType.length > 0; const hasCommentIssues = shouldCheckComments && - (pluginStats.missingComments.length > 0 || pluginStats.paramDocMismatches.length > 0); + (pluginStats.missingComments.length > 0 || + pluginStats.paramDocMismatches.length > 0 || + pluginStats.missingComplexTypeInfo.length > 0); const hasExportIssues = shouldCheckExports && missingExports > 0; return { diff --git a/packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts b/packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts index 60020dc6527c9..e2446555430cd 100644 --- a/packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts +++ b/packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts @@ -78,6 +78,7 @@ describe('collectStats', () => { isAnyType: [], noReferences: [], paramDocMismatches: [], + missingComplexTypeInfo: [], missingExports: 0, deprecatedAPIsReferencedCount: 0, unreferencedDeprecatedApisCount: 0, diff --git a/packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts b/packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts index 80449fd6d990d..b927a026a8ab8 100644 --- a/packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts +++ b/packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts @@ -78,6 +78,7 @@ describe('reportMetrics', () => { 'test-plugin': { apiCount: 5, missingComments: [], + missingComplexTypeInfo: [], isAnyType: [], noReferences: [], paramDocMismatches: [], diff --git a/packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts b/packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts index 415515b21cec8..2465777aabdb9 100644 --- a/packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts +++ b/packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts @@ -90,6 +90,7 @@ describe('writeDocs', () => { 'test-plugin': { apiCount: 5, missingComments: [], + missingComplexTypeInfo: [], isAnyType: [], noReferences: [], paramDocMismatches: [], diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts index aeca09816dc93..6ce10161ba765 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts @@ -17,6 +17,8 @@ export interface ImACommonType { // missing comments (2): // line 12 - ImACommonType // line 13 - goo +// missing complex type info (1): +// line 12 - ImACommonType // no references (2): // line 12 - ImACommonType // line 13 - goo diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts index 9635d3d4febf3..d3681bf9efbf2 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts @@ -132,6 +132,9 @@ export interface IReturnAReactComponent { // line 52 - Constructor // line 91 - anOptionalFn // line 101 - fnTypeWithGeneric +// missing complex type info (2): +// line 50 - component +// line 117 - component // no references (23): // line 28 - WithGen // line 32 - t diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts index 18b58e4080c12..aa6ea1bf3ea4c 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts @@ -91,6 +91,8 @@ export const literalString = 'HI'; // line 19 - notAnArrowFn // line 24 - aPropertyMisdirection // line 29 - aPropertyInlineFn +// missing complex type info (1): +// line 32 - a // no references (14): // line 18 - aPretendNamespaceObj // line 19 - notAnArrowFn diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts index 6cbcd63764c24..9fcbf236da06b 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts @@ -112,6 +112,10 @@ export const iShouldBeInternalFn = () => 'hi'; // param doc mismatches (2): // line 83 - fnWithNonExportedRef // line 85 - NotAnArrowFnType +// missing complex type info (3): +// line 27 - d +// line 27 - d +// line 27 - d // no references (40): // line 13 - notAnArrowFn // line 24 - a diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts index 64d665cf9a966..fb76ca82b9696 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts @@ -47,6 +47,10 @@ export function plugin() { // line 30 - new // param doc mismatches (1): // line 30 - new +// missing complex type info (3): +// line 24 - InterfaceWithIndexSignature +// line 28 - ClassConstructorWithStaticProperties +// line 30 - config // any usage (1): // line 20 - imAnAny // no references (9): diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts index 245793054f63b..b4445e2222a2a 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts @@ -188,6 +188,8 @@ export class PluginA implements PluginMock { // line 135 - param // param doc mismatches (1): // line 135 - fn +// missing complex type info (1): +// line 135 - foo // no references (23): // line 19 - SearchSpec // line 24 - username diff --git a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts index e396784906664..e76f1407adb0d 100644 --- a/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts +++ b/packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts @@ -84,6 +84,11 @@ export type AReactElementFn = () => ReactElement; // line 30 - FnTypeWithGeneric // line 54 - foo // line 62 - bar +// missing complex type info (4): +// line 36 - p +// line 36 - p +// line 53 - ImAnObject +// line 60 - MyProps // no references (21): // line 14 - StringOrUndefinedType // line 19 - TypeWithGeneric diff --git a/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts b/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts index 6b436988f1a3e..1da8607ffc720 100644 --- a/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts +++ b/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts @@ -153,11 +153,13 @@ beforeAll(async () => { missingExports: pluginAStats.missingExports, missingComments: pluginAStats.missingComments.length, paramDocMismatches: pluginAStats.paramDocMismatches.length, + missingComplexTypeInfo: pluginAStats.missingComplexTypeInfo.length, isAnyType: pluginAStats.isAnyType.length, noReferences: pluginAStats.noReferences.length, }, missingComments: pluginAStats.missingComments.map(mapStat), paramDocMismatches: pluginAStats.paramDocMismatches.map(mapStat), + missingComplexTypeInfo: pluginAStats.missingComplexTypeInfo.map(mapStat), isAnyType: pluginAStats.isAnyType.map(mapStat), noReferences: pluginAStats.noReferences.map(mapStat), }; diff --git a/packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json b/packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json index 3ab7a37d4f29f..9ab45220e4a32 100644 --- a/packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json +++ b/packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json @@ -4,6 +4,7 @@ "missingExports": 2, "missingComments": 64, "paramDocMismatches": 13, + "missingComplexTypeInfo": 15, "isAnyType": 1, "noReferences": 135 }, @@ -627,6 +628,128 @@ "columnNumber": 3 } ], + "missingComplexTypeInfo": [ + { + "id": "def-public.Setup.fnWithInlineParams.$1.fn.$1", + "label": "foo", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts", + "type": "Object", + "lineNumber": 135, + "columnNumber": 15 + }, + { + "id": "def-public.InterfaceWithIndexSignature", + "label": "InterfaceWithIndexSignature", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts", + "type": "Interface", + "lineNumber": 24, + "columnNumber": 1 + }, + { + "id": "def-public.ClassConstructorWithStaticProperties", + "label": "ClassConstructorWithStaticProperties", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts", + "type": "Interface", + "lineNumber": 28, + "columnNumber": 1 + }, + { + "id": "def-public.ClassConstructorWithStaticProperties.new.$1", + "label": "config", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts", + "type": "Object", + "lineNumber": 30, + "columnNumber": 16 + }, + { + "id": "def-public.NotAnArrowFnType.$4", + "label": "d", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts", + "type": "CompoundType", + "lineNumber": 27, + "columnNumber": 3 + }, + { + "id": "def-public.ExampleClass.component", + "label": "component", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts", + "type": "CompoundType", + "lineNumber": 50, + "columnNumber": 3 + }, + { + "id": "def-public.ExampleInterface.fnTypeWithGeneric.$2", + "label": "p", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts", + "type": "Object", + "lineNumber": 36, + "columnNumber": 43 + }, + { + "id": "def-public.IReturnAReactComponent.component", + "label": "component", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts", + "type": "CompoundType", + "lineNumber": 117, + "columnNumber": 3 + }, + { + "id": "def-public.aPretendNamespaceObj.notAnArrowFn.$4", + "label": "d", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts", + "type": "CompoundType", + "lineNumber": 27, + "columnNumber": 3 + }, + { + "id": "def-public.aPretendNamespaceObj.aPropertyMisdirection.$4", + "label": "d", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts", + "type": "CompoundType", + "lineNumber": 27, + "columnNumber": 3 + }, + { + "id": "def-public.aPretendNamespaceObj.aPropertyInlineFn.$1", + "label": "a", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts", + "type": "CompoundType", + "lineNumber": 32, + "columnNumber": 23 + }, + { + "id": "def-public.FnTypeWithGeneric.$2", + "label": "p", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts", + "type": "Object", + "lineNumber": 36, + "columnNumber": 43 + }, + { + "id": "def-public.ImAnObject", + "label": "ImAnObject", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts", + "type": "Interface", + "lineNumber": 53, + "columnNumber": 1 + }, + { + "id": "def-public.MyProps", + "label": "MyProps", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts", + "type": "Interface", + "lineNumber": 60, + "columnNumber": 1 + }, + { + "id": "def-common.ImACommonType", + "label": "ImACommonType", + "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/common/index.ts", + "type": "Interface", + "lineNumber": 12, + "columnNumber": 1 + } + ], "isAnyType": [ { "id": "def-public.imAnAny", diff --git a/packages/kbn-docs-utils/src/stats.ts b/packages/kbn-docs-utils/src/stats.ts index 13b1731c51782..217aa7f0d9407 100644 --- a/packages/kbn-docs-utils/src/stats.ts +++ b/packages/kbn-docs-utils/src/stats.ts @@ -27,6 +27,7 @@ export function collectApiStatsForPlugin(doc: PluginApi, issues: IssuesByPlugin) isAnyType: [], noReferences: [], paramDocMismatches: [], + missingComplexTypeInfo: [], deprecatedAPIsReferencedCount: 0, unreferencedDeprecatedApisCount: 0, adoptionTrackedAPIs: [], @@ -75,6 +76,7 @@ function collectStatsForApi(doc: ApiDeclaration, stats: ApiStats, pluginApi: Plu } trackParamDocMismatches(doc, stats); + trackMissingComplexTypeInfo(doc, stats); if (doc.type === TypeKind.AnyKind) { stats.isAnyType.push(doc); @@ -130,6 +132,22 @@ const trackParamDocMismatches = (doc: ApiDeclaration, stats: ApiStats): void => } }; +/** + * Tracks complex types (objects, interfaces, compound types) missing descriptions. + */ +const trackMissingComplexTypeInfo = (doc: ApiDeclaration, stats: ApiStats): void => { + const complexKinds = new Set([ + TypeKind.ObjectKind, + TypeKind.InterfaceKind, + TypeKind.CompoundTypeKind, + ]); + if (!complexKinds.has(doc.type)) return; + const hasDescription = doc.description !== undefined && doc.description.length > 0; + if (!hasDescription) { + stats.missingComplexTypeInfo.push(doc); + } +}; + function countApiForPlugin(doc: PluginApi) { return ( doc.client.reduce((sum, def) => { diff --git a/packages/kbn-docs-utils/src/types.ts b/packages/kbn-docs-utils/src/types.ts index 0721feb54dc16..f25bc3ae0151e 100644 --- a/packages/kbn-docs-utils/src/types.ts +++ b/packages/kbn-docs-utils/src/types.ts @@ -294,6 +294,7 @@ export interface ApiStats { isAnyType: ApiDeclaration[]; noReferences: ApiDeclaration[]; paramDocMismatches: ApiDeclaration[]; + missingComplexTypeInfo: ApiDeclaration[]; apiCount: number; missingExports: number; deprecatedAPIsReferencedCount: number;