From e4dc03a8b17d5e9f167de6a62a645878ac7ef3e2 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Wed, 10 Jun 2020 14:57:21 -0400
Subject: [PATCH] feat(types): adjust type exports for manual render function
 and tooling 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
---
 api-extractor.json                             |  4 ++++
 .../runtime-core/src/helpers/createSlots.ts    |  2 +-
 .../runtime-core/src/helpers/renderList.ts     | 10 ++++------
 .../runtime-core/src/helpers/renderSlot.ts     |  2 +-
 .../runtime-core/src/helpers/resolveAssets.ts  | 16 ++++++++++++++--
 packages/runtime-core/src/helpers/scopeId.ts   |  6 +++---
 .../runtime-core/src/helpers/toHandlers.ts     |  2 +-
 .../src/helpers/withRenderContext.ts           |  2 +-
 packages/runtime-core/src/index.ts             |  4 ++--
 packages/runtime-core/src/vnode.ts             | 12 ++++++------
 packages/runtime-dom/src/directives/vModel.ts  | 18 +-----------------
 packages/runtime-dom/src/directives/vOn.ts     |  4 ++--
 packages/runtime-dom/src/directives/vShow.ts   |  3 ---
 13 files changed, 40 insertions(+), 45 deletions(-)

diff --git a/api-extractor.json b/api-extractor.json
index 5d26120d..883bf47a 100644
--- 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
index f6c9c992..ed92b2cb 100644
--- 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
index 810ec1ed..f8238a46 100644
--- 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
index 41d942b2..75d8c511 100644
--- 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
index f7118a88..3f11cc9a 100644
--- 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
index 6c30ca10..fbefe04a 100644
--- a/packages/runtime-core/src/helpers/scopeId.ts
+++ b/packages/runtime-core/src/helpers/scopeId.ts
@@ -8,14 +8,14 @@ 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()
@@ -23,7 +23,7 @@ export function popScopeId() {
 }
 
 /**
- * @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
index a87b9e68..a7beede7 100644
--- 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
index f8aeb397..a8f326d0 100644
--- 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
index 5f805552..ed929a02 100644
--- 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
index 235c097c..b1d02603 100644
--- 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
index a0ae5ff6..2caab0a7 100644
--- 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
index 155ee8e2..ce4a4d0c 100644
--- 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
index 27a64245..2b1d9cae 100644
--- 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