Remove all apis tagged @internal and add tests

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_api_declaration.ts

@@ -10,7 +10,7 @@ import { Node } from 'ts-morph';
 import { ToolingLog, KibanaPlatformPlugin } from '@kbn/dev-utils';
 import { buildClassDec } from './build_class_dec';
 import { buildFunctionDec } from './build_function_dec';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { isNamedNode } from '../tsmorph_utils';
 import { AnchorLink, ApiDeclaration } from '../types';
 import { buildVariableDec } from './build_variable_dec';
@@ -80,6 +80,7 @@ export function buildApiDeclaration(
     id: getApiSectionId(anchorLink),
     type: getTypeKind(node),
     label: apiName,
+    tags: getJSDocTagNames(node),
     description: getCommentsFromNode(node),
     source: getSourceForNode(node),
     signature: getSignature(node, plugins, log),

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_arrow_fn_dec.ts

@@ -17,7 +17,7 @@ import {
   PropertyAssignment,
 } from 'ts-morph';
 import { getApiSectionId } from '../utils';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { AnchorLink, TypeKind } from '../types';
 import { getSourceForNode } from './utils';
 import { buildApiDecsForParameters } from './build_parameter_decs';
@@ -55,6 +55,7 @@ export function getArrowFunctionDec(
     description: getCommentsFromNode(node),
     label: node.getName(),
     source: getSourceForNode(node),
+    tags: getJSDocTagNames(node),
     returnComment: getJSDocReturnTagComment(node),
   };
 }

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_class_dec.ts

@@ -9,10 +9,10 @@
 import { ToolingLog, KibanaPlatformPlugin } from '@kbn/dev-utils';
 import { ClassDeclaration } from 'ts-morph';
 import { AnchorLink, ApiDeclaration, TypeKind } from '../types';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { buildApiDeclaration } from './build_api_declaration';
 import { getSourceForNode, isPrivate } from './utils';
-import { getApiSectionId } from '../utils';
+import { getApiSectionId, isInternal } from '../utils';
 import { getSignature } from './get_signature';
 
 export function buildClassDec(
@@ -24,21 +24,23 @@ export function buildClassDec(
   return {
     id: getApiSectionId(anchorLink),
     type: TypeKind.ClassKind,
+    tags: getJSDocTagNames(node),
     label: node.getName() || 'Missing label',
     description: getCommentsFromNode(node),
     signature: getSignature(node, plugins, log),
     children: node.getMembers().reduce((acc, m) => {
       if (!isPrivate(m)) {
-        acc.push(
-          buildApiDeclaration(
-            m,
-            plugins,
-            log,
-            anchorLink.pluginName,
-            anchorLink.scope,
-            anchorLink.apiName
-          )
+        const child = buildApiDeclaration(
+          m,
+          plugins,
+          log,
+          anchorLink.pluginName,
+          anchorLink.scope,
+          anchorLink.apiName
         );
+        if (!isInternal(child)) {
+          acc.push(child);
+        }
       }
       return acc;
     }, [] as ApiDeclaration[]),

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_function_dec.ts

@@ -39,7 +39,7 @@ export function buildFunctionDec(
   const label = Node.isConstructorDeclaration(node)
     ? 'Constructor'
     : node.getName() || '(WARN: Missing name)';
-  return {
+  const fn = {
     id: getApiSectionId(anchorLink),
     type: TypeKind.FunctionKind,
     label,
@@ -56,4 +56,7 @@ export function buildFunctionDec(
     returnComment: getJSDocReturnTagComment(node),
     source: getSourceForNode(node),
   };
+
+  log.warning(`fn ${label} has tags: ${fn.tags.join(', ')}`);
+  return fn;
 }

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_interface_dec.ts

@@ -9,10 +9,10 @@
 import { ToolingLog, KibanaPlatformPlugin } from '@kbn/dev-utils';
 import { InterfaceDeclaration } from 'ts-morph';
 import { AnchorLink, ApiDeclaration, TypeKind } from '../types';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { buildApiDeclaration } from './build_api_declaration';
 import { getSourceForNode } from './utils';
-import { getApiSectionId } from '../utils';
+import { getApiSectionId, isInternal } from '../utils';
 import { getSignature } from './get_signature';
 
 export function buildInterfaceDec(
@@ -27,18 +27,21 @@ export function buildInterfaceDec(
     label: node.getName(),
     signature: getSignature(node, plugins, log),
     description: getCommentsFromNode(node),
-    children: node
-      .getMembers()
-      .map((m) =>
-        buildApiDeclaration(
-          m,
-          plugins,
-          log,
-          anchorLink.pluginName,
-          anchorLink.scope,
-          anchorLink.apiName
-        )
-      ),
+    tags: getJSDocTagNames(node),
+    children: node.getMembers().reduce((acc, m) => {
+      const child = buildApiDeclaration(
+        m,
+        plugins,
+        log,
+        anchorLink.pluginName,
+        anchorLink.scope,
+        anchorLink.apiName
+      );
+      if (!isInternal(child)) {
+        acc.push(child);
+      }
+      return acc;
+    }, [] as ApiDeclaration[]),
     source: getSourceForNode(node),
   };
 }

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_type_literal_dec.ts

@@ -9,7 +9,7 @@
 import { ToolingLog, KibanaPlatformPlugin } from '@kbn/dev-utils';
 import { TypeLiteralNode } from 'ts-morph';
 import { getApiSectionId } from '../utils';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { AnchorLink, ApiDeclaration, TypeKind } from '../types';
 import { buildApiDeclaration } from './build_api_declaration';
 import { getSourceForNode } from './utils';
@@ -37,6 +37,7 @@ export function buildTypeLiteralDec(
     id: getApiSectionId(anchorLink),
     type: TypeKind.ObjectKind,
     label: name,
+    tags: getJSDocTagNames(node),
     description: getCommentsFromNode(node),
     children: node
       .getMembers()

packages/kbn-docs-utils/src/api_docs/build_api_declarations/build_variable_dec.ts

@@ -15,8 +15,8 @@ import {
   PropertySignature,
   ShorthandPropertyAssignment,
 } from 'ts-morph';
-import { getApiSectionId } from '../utils';
-import { getCommentsFromNode } from './js_doc_utils';
+import { getApiSectionId, isInternal } from '../utils';
+import { getCommentsFromNode, getJSDocTagNames } from './js_doc_utils';
 import { AnchorLink, ApiDeclaration, TypeKind } from '../types';
 import { getArrowFunctionDec } from './build_arrow_fn_dec';
 import { buildApiDeclaration } from './build_api_declaration';
@@ -51,16 +51,21 @@ export function buildVariableDec(
     return {
       id: getApiSectionId(anchorLink),
       type: TypeKind.ObjectKind,
-      children: initializer.getProperties().map((prop) => {
-        return buildApiDeclaration(
+      tags: getJSDocTagNames(node),
+      children: initializer.getProperties().reduce((acc, prop) => {
+        const child = buildApiDeclaration(
           prop,
           plugins,
           log,
           anchorLink.pluginName,
           anchorLink.scope,
           anchorLink.apiName
         );
-      }),
+        if (!isInternal(child)) {
+          acc.push(child);
+        }
+        return acc;
+      }, [] as ApiDeclaration[]),
       description: getCommentsFromNode(node),
       label: node.getName(),
       source: getSourceForNode(node),
@@ -71,6 +76,7 @@ export function buildVariableDec(
 
   // Otherwise return it just as a single entry.
   return {
+    tags: getJSDocTagNames(node),
     id: getApiSectionId(anchorLink),
     type: getTypeKind(node),
     label: node.getName(),

packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/classes.ts

@@ -10,6 +10,20 @@
 
 import { ImAType } from './types';
 
+/**
+ * @internal
+ */
+export class IShouldBeInternalClass {
+  st: string;
+}
+
+/**
+ * @internal
+ */
+export interface IShouldBeInternalInterface {
+  st: string;
+}
+
 /**
  * An interface with a generic.
  */

packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/const_vars.ts

@@ -45,6 +45,13 @@ export const aPretendNamespaceObj = {
   },
 };
 
+/**
+ * @internal
+ */
+export const iShouldBeInternalObj = {
+  foo: 'hi',
+};
+
 /**
  * This is a complicated union type
  */

packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/fns.ts

@@ -76,3 +76,8 @@ interface ImNotExported {
 export const fnWithNonExportedRef = (a: ImNotExported) => 'shi';
 
 export type NotAnArrowFnType = typeof notAnArrowFn;
+
+/**
+ * @internal
+ */
+export const iShouldBeInternalFn = () => 'hi';

packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/plugin.ts

@@ -66,6 +66,11 @@ export interface Start {
    * @returns The currently selected {@link SearchLanguage}
    */
   getSearchLanguage: () => SearchLanguage;
+
+  /**
+   * @internal
+   */
+  anInternalStartFn: () => string;
 }
 
 /**

packages/kbn-docs-utils/src/api_docs/tests/__fixtures__/src/plugin_a/public/types.ts

@@ -43,3 +43,6 @@ export type IRefANotExportedType = ImNotExportedFromIndex | { zed: 'hi' };
 export interface ImAnObject {
   foo: FnWithGeneric;
 }
+
+/** @internal */
+export type IShouldBeInternal = string | { foo: string };

packages/kbn-docs-utils/src/api_docs/tests/api_doc_suite.test.ts

@@ -170,9 +170,19 @@ describe('functions', () => {
     expect(fn2).toBeDefined();
     expect(fn2?.type).toBe(TypeKind.FunctionKind);
   });
+
+  it('Fn with internal tag is not exported', () => {
+    const fn = doc.client.find((c) => c.label === 'iShouldBeInternalFn');
+    expect(fn).toBeUndefined();
+  });
 });
 
 describe('objects', () => {
+  it('Object with internal tag is not exported', () => {
+    const obj = doc.client.find((c) => c.label === 'iShouldBeInternalObj');
+    expect(obj).toBeUndefined();
+  });
+
   it('Object exported correctly', () => {
     const obj = doc.client.find((c) => c.label === 'aPretendNamespaceObj');
     expect(obj).toBeDefined();
@@ -297,6 +307,11 @@ describe('Misc types', () => {
     expect(linkCount(type?.signature!)).toBe(3);
     expect((type!.signature![1] as Reference).docId).toBe('kibPluginAFooPluginApi');
   });
+
+  it('types with internal tags are not exported', () => {
+    const internal = doc.client.find((c) => c.label === 'IShouldBeInternal');
+    expect(internal).toBeUndefined();
+  });
 });
 
 describe('interfaces and classes', () => {
@@ -394,4 +409,21 @@ describe('interfaces and classes', () => {
     expect(fnWithGeneric).toBeDefined();
     expect(fnWithGeneric?.type).toBe(TypeKind.FunctionKind);
   });
+
+  it('interfaces with internal tags are not exported', () => {
+    const internal = doc.client.find((c) => c.label === 'IShouldBeInternalInterface');
+    expect(internal).toBeUndefined();
+  });
+
+  it('classes with internal tags are not exported', () => {
+    const clss = doc.client.find((c) => c.label === 'IShouldBeInternalClass');
+    expect(clss).toBeUndefined();
+  });
+
+  it('interface property marked as internal not exported', () => {
+    const start = doc.client.find((c) => c.label === 'Start');
+
+    const internal = start?.children?.find((c) => c.label === 'anInternalStartFn');
+    expect(internal).toBeUndefined();
+  });
 });