From: Evan You Date: Thu, 7 May 2020 15:01:36 +0000 (-0400) Subject: refactor(compiler/types): convert compiler options documentation to jsdoc X-Git-Tag: v3.0.0-beta.10~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e58beecc97635ea61e39b84ea406fcc42166095b;p=thirdparty%2Fvuejs%2Fcore.git refactor(compiler/types): convert compiler options documentation to jsdoc BREAKING CHANGE: `getTextMode` compiler option signature has changed from ```ts (tag: string, ns: string, parent: ElementNode | undefined) => TextModes ``` to ```ts (node: ElementNode, parent: ElementNode | undefined) => TextModes ``` --- diff --git a/packages/compiler-core/__tests__/parse.spec.ts b/packages/compiler-core/__tests__/parse.spec.ts index f556f5bc90..e3345a0f26 100644 --- 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 index 056ea90fe8..087d8bcfe6 100644 --- 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.
for browsers + /** + * e.g. platform native elements, e.g.
for browsers + */ isNativeTag?: (tag: string) => boolean - // e.g. native elements that can self-close, e.g. ,
,
+ /** + * e.g. native elements that can self-close, e.g. ,
,
+ */ isVoidTag?: (tag: string) => boolean - // e.g. elements that should preserve whitespace inside, e.g. 
+  /**
+   * e.g. elements that should preserve whitespace inside, e.g. 
+   */
   isPreTag?: (tag: string) => boolean
-  // platform-specific built-in components e.g. 
+  /**
+   * Platform-specific built-in components e.g. 
+   */
   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
-  // 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
index ee0e07635b..5e526bc2f5 100644
--- 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
index 5874260501..443210e333 100644
--- 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
index 4b1c972f8d..ce466ba672 100644
--- 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