refactor(compiler/types): convert compiler options documentation to jsdoc

yyx990803 · yyx990803 · commit e58beecc9763 · 2020-05-07T11:01:36.000-04:00
BREAKING CHANGE: `getTextMode` compiler option signature has changed from

  ```ts
  (tag: string, ns: string, parent: ElementNode | undefined) =&gt; TextModes
  ```

  to

  ```ts
  (node: ElementNode, parent: ElementNode | undefined) =&gt; TextModes
  ```
diff --git a/packages/compiler-core/__tests__/parse.spec.ts b/packages/compiler-core/__tests__/parse.spec.ts
@@ -2515,7 +2515,7 @@ foo
                   }
                   return ns
                 },
-                getTextMode: tag => {
+                getTextMode: ({ tag }) => {
                   if (tag === 'textarea') {
                     return TextModes.RCDATA
                   }
diff --git a/packages/compiler-core/src/options.ts b/packages/compiler-core/src/options.ts
@@ -9,23 +9,44 @@ import {
 import { ParserPlugin } from '@babel/parser'
 
 export interface ParserOptions {
-  // e.g. platform native elements, e.g. <div> for browsers
+  /**
+   * e.g. platform native elements, e.g. <div> for browsers
+   */
   isNativeTag?: (tag: string) => boolean
-  // e.g. native elements that can self-close, e.g. <img>, <br>, <hr>
+  /**
+   * e.g. native elements that can self-close, e.g. <img>, <br>, <hr>
+   */
   isVoidTag?: (tag: string) => boolean
-  // e.g. elements that should preserve whitespace inside, e.g. <pre>
+  /**
+   * e.g. elements that should preserve whitespace inside, e.g. <pre>
+   */
   isPreTag?: (tag: string) => boolean
-  // platform-specific built-in components e.g. <Transition>
+  /**
+   * Platform-specific built-in components e.g. <Transition>
+   */
   isBuiltInComponent?: (tag: string) => symbol | void
-  // separate option for end users to extend the native elements list
+  /**
+   * Separate option for end users to extend the native elements list
+   */
   isCustomElement?: (tag: string) => boolean
+  /**
+   * Get tag namespace
+   */
   getNamespace?: (tag: string, parent: ElementNode | undefined) => Namespace
+  /**
+   * Get text parsing mode for this element
+   */
   getTextMode?: (
-    tag: string,
-    ns: Namespace,
+    node: ElementNode,
     parent: ElementNode | undefined
   ) => TextModes
-  delimiters?: [string, string] // ['{{', '}}']
+  /**
+   * @default ['{{', '}}']
+   */
+  delimiters?: [string, string]
+  /**
+   * Only needed for DOM compilers
+   */
   decodeEntities?: (rawText: string, asAttr: boolean) => string
   onError?: (error: CompilerError) => void
 }
@@ -36,64 +57,117 @@ export type HoistTransform = (
 ) => JSChildNode
 
 export interface TransformOptions {
+  /**
+   * An array of node trasnforms to be applied to every AST node.
+   */
   nodeTransforms?: NodeTransform[]
+  /**
+   * An object of { name: transform } to be applied to every directive attribute
+   * node found on element nodes.
+   */
   directiveTransforms?: Record<string, DirectiveTransform | undefined>
-  // an optional hook to transform a node being hoisted.
-  // used by compiler-dom to turn hoisted nodes into stringified HTML vnodes.
+  /**
+   * An optional hook to transform a node being hoisted.
+   * used by compiler-dom to turn hoisted nodes into stringified HTML vnodes.
+   * @default null
+   */
   transformHoist?: HoistTransform | null
+  /**
+   * If the pairing runtime provides additional built-in elements, use this to
+   * mark them as built-in so the compiler will generate component vnodes
+   * for them.
+   */
   isBuiltInComponent?: (tag: string) => symbol | void
-  // Transform expressions like {{ foo }} to `_ctx.foo`.
-  // If this option is false, the generated code will be wrapped in a
-  // `with (this) { ... }` block.
-  // - This is force-enabled in module mode, since modules are by default strict
-  //   and cannot use `with`
-  // - Default: mode === 'module'
+  /**
+   * Transform expressions like {{ foo }} to `_ctx.foo`.
+   * If this option is false, the generated code will be wrapped in a
+   * `with (this) { ... }` block.
+   * - This is force-enabled in module mode, since modules are by default strict
+   * and cannot use `with`
+   * @default mode === 'module'
+   */
   prefixIdentifiers?: boolean
-  // Hoist static VNodes and props objects to `_hoisted_x` constants
-  // - Default: false
+  /**
+   * Hoist static VNodes and props objects to `_hoisted_x` constants
+   * @default false
+   */
   hoistStatic?: boolean
-  // Cache v-on handlers to avoid creating new inline functions on each render,
-  // also avoids the need for dynamically patching the handlers by wrapping it.
-  // e.g `@click="foo"` by default is compiled to `{ onClick: foo }`. With this
-  // option it's compiled to:
-  // `{ onClick: _cache[0] || (_cache[0] = e => _ctx.foo(e)) }`
-  // - Requires "prefixIdentifiers" to be enabled because it relies on scope
-  //   analysis to determine if a handler is safe to cache.
-  // - Default: false
+  /**
+   * Cache v-on handlers to avoid creating new inline functions on each render,
+   * also avoids the need for dynamically patching the handlers by wrapping it.
+   * e.g `@click="foo"` by default is compiled to `{ onClick: foo }`. With this
+   * option it's compiled to:
+   * ```js
+   * { onClick: _cache[0] || (_cache[0] = e => _ctx.foo(e)) }
+   * ```
+   * - Requires "prefixIdentifiers" to be enabled because it relies on scope
+   * analysis to determine if a handler is safe to cache.
+   * @default false
+   */
   cacheHandlers?: boolean
-  // a list of parser plugins to enable for @babel/parser
-  // https://babeljs.io/docs/en/next/babel-parser#plugins
+  /**
+   * A list of parser plugins to enable for `@babel/parser`, which is used to
+   * parse expressions in bindings and interpolations.
+   * https://babeljs.io/docs/en/next/babel-parser#plugins
+   */
   expressionPlugins?: ParserPlugin[]
-  // SFC scoped styles ID
+  /**
+   * SFC scoped styles ID
+   */
   scopeId?: string | null
+  /**
+   * Generate SSR-optimized render functions instead.
+   * The resulting funciton must be attached to the component via the
+   * `ssrRender` option instead of `render`.
+   */
   ssr?: boolean
   onError?: (error: CompilerError) => void
 }
 
 export interface CodegenOptions {
-  // - Module mode will generate ES module import statements for helpers
-  //   and export the render function as the default export.
-  // - Function mode will generate a single `const { helpers... } = Vue`
-  //   statement and return the render function. It is meant to be used with
-  //   `new Function(code)()` to generate a render function at runtime.
-  // - Default: 'function'
+  /**
+   * - `module` mode will generate ES module import statements for helpers
+   * and export the render function as the default export.
+   * - `function` mode will generate a single `const { helpers... } = Vue`
+   * statement and return the render function. It expects `Vue` to be globally
+   * available (or passed by wrapping the code with an IIFE). It is meant to be
+   * used with `new Function(code)()` to generate a render function at runtime.
+   * @default 'function'
+   */
   mode?: 'module' | 'function'
-  // Generate source map?
-  // - Default: false
+  /**
+   * Generate source map?
+   * @default false
+   */
   sourceMap?: boolean
-  // Filename for source map generation.
-  // - Default: `template.vue.html`
+  /**
+   * Filename for source map generation.
+   * @default 'template.vue.html'
+   */
   filename?: string
-  // SFC scoped styles ID
+  /**
+   * SFC scoped styles ID
+   */
   scopeId?: string | null
-  // we need to know about this to generate proper preambles
-  prefixIdentifiers?: boolean
-  // option to optimize helper import bindings via variable assignment
-  // (only used for webpack code-split)
+  /**
+   * Option to optimize helper import bindings via variable assignment
+   * (only used for webpack code-split)
+   * @default false
+   */
   optimizeBindings?: boolean
-  // for specifying where to import helpers
+  /**
+   * Customize where to import runtime helpers from.
+   * @default 'vue'
+   */
   runtimeModuleName?: string
+  /**
+   * Customize the global variable name of `Vue` to get helpers from
+   * in function mode
+   * @default 'Vue'
+   */
   runtimeGlobalName?: string
+  // we need to know this during codegen to generate proper preambles
+  prefixIdentifiers?: boolean
   // generate ssr-specific code?
   ssr?: boolean
 }
diff --git a/packages/compiler-core/src/parse.ts b/packages/compiler-core/src/parse.ts
@@ -373,7 +373,7 @@ function parseElement(
 
   // Children.
   ancestors.push(element)
-  const mode = context.options.getTextMode(element.tag, element.ns, parent)
+  const mode = context.options.getTextMode(element, parent)
   const children = parseChildren(context, mode, ancestors)
   ancestors.pop()
 
diff --git a/packages/compiler-dom/src/parserOptions.ts b/packages/compiler-dom/src/parserOptions.ts
@@ -86,7 +86,7 @@ export const parserOptions: ParserOptions = {
   },
 
   // https://html.spec.whatwg.org/multipage/parsing.html#parsing-html-fragments
-  getTextMode(tag: string, ns: DOMNamespaces): TextModes {
+  getTextMode({ tag, ns }: ElementNode): TextModes {
     if (ns === DOMNamespaces.HTML) {
       if (tag === 'textarea' || tag === 'title') {
         return TextModes.RCDATA
diff --git a/packages/compiler-sfc/src/parse.ts b/packages/compiler-sfc/src/parse.ts
@@ -96,7 +96,7 @@ export function parse(
     isNativeTag: () => true,
     // preserve all whitespaces
     isPreTag: () => true,
-    getTextMode: (tag, _ns, parent) => {
+    getTextMode: ({ tag }, parent) => {
       // all top level elements except <template> are parsed as raw text
       // containers
       if (!parent && tag !== 'template') {

Original file line number	Diff line number	Diff line change
`@@ -2515,7 +2515,7 @@ foo`
`2515`	`2515`	`}`
`2516`	`2516`	`return ns`
`2517`	`2517`	`},`
`2518`		`- getTextMode: tag => {`
	`2518`	`+ getTextMode: ({ tag }) => {`
`2519`	`2519`	`if (tag === 'textarea') {`
`2520`	`2520`	`return TextModes.RCDATA`
`2521`	`2521`	`}`