feat(types): adjust type exports for manual render function and tooli…

…ng usage - v-model and v-show directives are now exposed as public - compiler-used runtime helpers are now exposed for TS tooling, but marked as @Private close #1329
vuejs · Jun 10, 2020 · e4dc03a · e4dc03a
1 parent 9b5d13e
commit e4dc03a
Show file tree

Hide file tree

Showing 13 changed files with 40 additions and 45 deletions.
diff --git a/api-extractor.json b/api-extractor.json
@@ -40,6 +40,10 @@
     "tsdocMessageReporting": {
       "default": {
         "logLevel": "warning"
+      },
+
+      "tsdoc-undefined-tag": {
+        "logLevel": "none"
       }
     }
   }

diff --git a/packages/runtime-core/src/helpers/createSlots.ts b/packages/runtime-core/src/helpers/createSlots.ts
@@ -8,7 +8,7 @@ interface CompiledSlotDescriptor {
 
 /**
  * Compiler runtime helper for creating dynamic slots object
- * @internal
+ * @private
  */
 export function createSlots(
   slots: Record<string, Slot>,

diff --git a/packages/runtime-core/src/helpers/renderList.ts b/packages/runtime-core/src/helpers/renderList.ts
@@ -3,7 +3,7 @@ import { isArray, isString, isObject } from '@vue/shared'
 
 /**
  * v-for string
- * @internal
+ * @private
  */
 export function renderList(
   source: string,
@@ -12,7 +12,6 @@ export function renderList(
 
 /**
  * v-for number
- * @internal
  */
 export function renderList(
   source: number,
@@ -21,7 +20,6 @@ export function renderList(
 
 /**
  * v-for array
- * @internal
  */
 export function renderList<T>(
   source: T[],
@@ -30,7 +28,6 @@ export function renderList<T>(
 
 /**
  * v-for iterable
- * @internal
  */
 export function renderList<T>(
   source: Iterable<T>,
@@ -39,7 +36,6 @@ export function renderList<T>(
 
 /**
  * v-for object
- * @internal
  */
 export function renderList<T>(
   source: T,
@@ -50,7 +46,9 @@ export function renderList<T>(
   ) => VNodeChild
 ): VNodeChild[]
 
-// actual implementation
+/**
+ * Actual implementation
+ */
 export function renderList(
   source: any,
   renderItem: (...args: any[]) => VNodeChild

diff --git a/packages/runtime-core/src/helpers/renderSlot.ts b/packages/runtime-core/src/helpers/renderSlot.ts
@@ -12,7 +12,7 @@ import { warn } from '../warning'
 
 /**
  * Compiler runtime helper for rendering <slot/>
- * @internal
+ * @private
  */
 export function renderSlot(
   slots: Slots,

diff --git a/packages/runtime-core/src/helpers/resolveAssets.ts b/packages/runtime-core/src/helpers/resolveAssets.ts
@@ -12,12 +12,18 @@ import { warn } from '../warning'
 const COMPONENTS = 'components'
 const DIRECTIVES = 'directives'
 
+/**
+ * @private
+ */
 export function resolveComponent(name: string): Component | string | undefined {
   return resolveAsset(COMPONENTS, name) || name
 }
 
 export const NULL_DYNAMIC_COMPONENT = Symbol()
 
+/**
+ * @private
+ */
 export function resolveDynamicComponent(
   component: unknown
 ): Component | string | typeof NULL_DYNAMIC_COMPONENT {
@@ -29,11 +35,17 @@ export function resolveDynamicComponent(
   }
 }
 
+/**
+ * @private
+ */
 export function resolveDirective(name: string): Directive | undefined {
   return resolveAsset(DIRECTIVES, name)
 }
 
-// overload 1: components
+/**
+ * @private
+ * overload 1: components
+ */
 function resolveAsset(
   type: typeof COMPONENTS,
   name: string,
@@ -44,7 +56,7 @@ function resolveAsset(
   type: typeof DIRECTIVES,
   name: string
 ): Directive | undefined
-
+// implementation
 function resolveAsset(
   type: typeof COMPONENTS | typeof DIRECTIVES,
   name: string,

diff --git a/packages/runtime-core/src/helpers/scopeId.ts b/packages/runtime-core/src/helpers/scopeId.ts
@@ -8,22 +8,22 @@ export let currentScopeId: string | null = null
 const scopeIdStack: string[] = []
 
 /**
- * @internal
+ * @private
  */
 export function pushScopeId(id: string) {
   scopeIdStack.push((currentScopeId = id))
 }
 
 /**
- * @internal
+ * @private
  */
 export function popScopeId() {
   scopeIdStack.pop()
   currentScopeId = scopeIdStack[scopeIdStack.length - 1] || null
 }
 
 /**
- * @internal
+ * @private
  */
 export function withScopeId(id: string): <T extends Function>(fn: T) => T {
   return ((fn: Function) =>

diff --git a/packages/runtime-core/src/helpers/toHandlers.ts b/packages/runtime-core/src/helpers/toHandlers.ts
@@ -3,7 +3,7 @@ import { warn } from '../warning'
 
 /**
  * For prefixing keys in v-on="obj" with "on"
- * @internal
+ * @private
  */
 export function toHandlers(obj: Record<string, any>): Record<string, any> {
   const ret: Record<string, any> = {}

diff --git a/packages/runtime-core/src/helpers/withRenderContext.ts b/packages/runtime-core/src/helpers/withRenderContext.ts
@@ -7,7 +7,7 @@ import { ComponentInternalInstance } from '../component'
 
 /**
  * Wrap a slot function to memoize current rendering instance
- * @internal
+ * @private
  */
 export function withCtx(
   fn: Slot,

diff --git a/packages/runtime-core/src/index.ts b/packages/runtime-core/src/index.ts
@@ -229,11 +229,11 @@ export {
 // them in @vue/shared's typings
 import { toDisplayString, camelize } from '@vue/shared'
 /**
- * @internal
+ * @private
  */
 const _toDisplayString = toDisplayString
 /**
- * @internal
+ * @private
  */
 const _camelize = camelize
 export { _toDisplayString as toDisplayString, _camelize as camelize }

diff --git a/packages/runtime-core/src/vnode.ts b/packages/runtime-core/src/vnode.ts
@@ -161,7 +161,7 @@ let currentBlock: VNode[] | null = null
  * disableTracking is true when creating a v-for fragment block, since a v-for
  * fragment always diffs its children.
  *
- * @internal
+ * @private
  */
 export function openBlock(disableTracking = false) {
   blockStack.push((currentBlock = disableTracking ? null : []))
@@ -187,7 +187,7 @@ let shouldTrack = 1
  * )
  * ```
  *
- * @internal
+ * @private
  */
 export function setBlockTracking(value: number) {
   shouldTrack += value
@@ -198,7 +198,7 @@ export function setBlockTracking(value: number) {
  * A block root keeps track of dynamic nodes within the block in the
  * `dynamicChildren` array.
  *
- * @internal
+ * @private
  */
 export function createBlock(
   type: VNodeTypes | ClassComponent,
@@ -453,14 +453,14 @@ export function cloneVNode<T, U>(
 }
 
 /**
- * @internal
+ * @private
  */
 export function createTextVNode(text: string = ' ', flag: number = 0): VNode {
   return createVNode(Text, null, text, flag)
 }
 
 /**
- * @internal
+ * @private
  */
 export function createStaticVNode(
   content: string,
@@ -474,7 +474,7 @@ export function createStaticVNode(
 }
 
 /**
- * @internal
+ * @private
  */
 export function createCommentVNode(
   text: string = '',

diff --git a/packages/runtime-dom/src/directives/vModel.ts b/packages/runtime-dom/src/directives/vModel.ts
@@ -42,11 +42,7 @@ function trigger(el: HTMLElement, type: string) {
 type ModelDirective<T> = ObjectDirective<T & { _assign: AssignerFn }>
 
 // We are exporting the v-model runtime directly as vnode hooks so that it can
-// be tree-shaken in case v-model is never used. These are used by compilers
-// only and userland code should avoid relying on them.
-/**
- * @internal
- */
+// be tree-shaken in case v-model is never used.
 export const vModelText: ModelDirective<
   HTMLInputElement | HTMLTextAreaElement
 > = {
@@ -96,9 +92,6 @@ export const vModelText: ModelDirective<
   }
 }
 
-/**
- * @internal
- */
 export const vModelCheckbox: ModelDirective<HTMLInputElement> = {
   beforeMount(el, binding, vnode) {
     setChecked(el, binding, vnode)
@@ -144,9 +137,6 @@ function setChecked(
   }
 }
 
-/**
- * @internal
- */
 export const vModelRadio: ModelDirective<HTMLInputElement> = {
   beforeMount(el, { value }, vnode) {
     el.checked = looseEqual(value, vnode.props!.value)
@@ -163,9 +153,6 @@ export const vModelRadio: ModelDirective<HTMLInputElement> = {
   }
 }
 
-/**
- * @internal
- */
 export const vModelSelect: ModelDirective<HTMLSelectElement> = {
   // use mounted & updated because <select> relies on its children <option>s.
   mounted(el, { value }, vnode) {
@@ -227,9 +214,6 @@ function getCheckboxValue(
   return key in el ? el[key] : checked
 }
 
-/**
- * @internal
- */
 export const vModelDynamic: ObjectDirective<
   HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
 > = {

diff --git a/packages/runtime-dom/src/directives/vOn.ts b/packages/runtime-dom/src/directives/vOn.ts
@@ -23,7 +23,7 @@ const modifierGuards: Record<
 }
 
 /**
- * @internal
+ * @private
  */
 export const withModifiers = (fn: Function, modifiers: string[]) => {
   return (event: Event, ...args: unknown[]) => {
@@ -48,7 +48,7 @@ const keyNames: Record<string, string | string[]> = {
 }
 
 /**
- * @internal
+ * @private
  */
 export const withKeys = (fn: Function, modifiers: string[]) => {
   return (event: KeyboardEvent) => {

diff --git a/packages/runtime-dom/src/directives/vShow.ts b/packages/runtime-dom/src/directives/vShow.ts
@@ -5,9 +5,6 @@ interface VShowElement extends HTMLElement {
   _vod: string
 }
 
-/**
- * @internal
- */
 export const vShow: ObjectDirective<VShowElement> = {
   beforeMount(el, { value }, { transition }) {
     el._vod = el.style.display === 'none' ? '' : el.style.display