docs: add some comments for patch-context.js

Author: SmallComfort

src/server/patch-context.js

@@ -100,8 +100,15 @@ export class PatchContext {
   }
 
   /**
-   * 合并子元素节点
-   * 注意：基于抽象语法树的推导优化依赖于稳定的模板结构，如果开发者使用了自定义 render，则无法对其进行语法树级别的推导优化
+   * English:
+   * Perform ast optimization on element type VNode.
+   *
+   * AST-based optimization relies on a stable template structure, which cannot be
+   * optimized if the developer uses a custom render
+   *
+   * 中文：
+   * 对元素类型节点执行 ast 优化
+   * 基于 ast 的优化依赖于稳定的模板结构，如果开发者使用了自定义 render，则无法做出优化
    */
   astShaking(patchState: PatchState) {
     const { endTag, staticChildren, ast } = patchState
@@ -121,10 +128,23 @@ export class PatchContext {
         return preV
       }, [])
 
-    /** 子节点是否全部都是静态节点 */
+    /**
+     * English:
+     * Detect whether all child nodes are static
+     *
+     * 中文：
+     * 检测子节点是否全部都是静态节点
+     */
     const childStatic = elements.length === 0 || (elements.length === 1 && typeof elements[0] === 'string')
 
-    /** 如果当前语法树并未匹配到组件 render 模板 则仅判断当前节点及其子节点是否全是静态 */
+    /**
+     * English:
+     * If the current ast does not match the component's rendering template, detect
+     * whether the current node and its children are all static.
+     *
+     * 中文：
+     * 如果当前 ast 并未匹配到组件 render 模板 则仅判断当前节点及其子节点是否全是静态
+     */
     if (ast.unMatchedAst) {
       if (ast.ssrString !== undefined && childStatic) {
         const str = ast.ssrString + elements[0] + endTag
@@ -134,11 +154,15 @@ export class PatchContext {
     }
 
     /**
+     * English:
+     * Resetting the current ast subtree.
+     * If children exist and the child element is not static, the ast for children is reconstructed.
+     *
+     * 中文：
      * 重新设置当前节点抽象语法树的子树
-     * ast 不一定有 children 子元素，但是其子元素有可能全部都是静态的，例如常量for循环
+     * 如果 children 存在，并且子元素非静态，则重新为 children 构建抽象语法树
      */
     const children = getVNodeAstChildren(ast)
-    /** 如果存在 AST 子元素，并且子元素非静态，则构建抽象语法树 */
     if (children && !childStatic) {
       children.elements = elements.map(v => {
         if (typeof v === 'string') {
@@ -151,7 +175,13 @@ export class PatchContext {
       })
     }
 
-    /** 如果当前节点和子节点都是静态节点，则将节点合并 */
+    /**
+     * English:
+     * If both the current node and child nodes are static, the nodes are combined.
+     *
+     * 中文：
+     * 如果当前节点和子节点都是静态节点，则将节点合并。
+     * */
     if (ast.ssrString !== undefined && childStatic){
       const str = ast.ssrString + elements[0] + endTag
       Object.assign(ast, callExpression(
@@ -161,22 +191,36 @@ export class PatchContext {
     }
 
     /**
+     * English:
+     * Optimizing the child tree of the current node abstract syntax tree
+     *
+     * 中文：
      * 优化当前节点抽象语法树的子树
      */
     this.reduceAstChildren(patchState)
   }
 
   /**
+   * English:
+   * Merge component-level VNodes.
+   * If the entire component is static, the result is passed up.
+   * If the component is dynamic, retain the rendering function.
+   *
+   * 中文：
    * 合并组件级节点
-   * 如果整个组件都是静态的，则将结果向上传递，如果组件是动态的，则保留渲染函数
-   *     * todo astComponentShaking 里面需要考虑到 unMatchedAst 静态情况
+   * 如果整个组件都是静态的，则将结果向上传递
+   * 如果组件是动态的，则保留渲染函数
    */
   astComponentShaking(patchState: PatchState) {
     const prevAst = patchState.prevAst
     const ssrRenderAst = prevAst.ssrRenderAst
 
     /**
-     * 当前组件无优化
+     * English:
+     * Current component nodes are not optimized.
+     *
+     * 中文：
+     * 当前组件节点无优化
      */
     if (ssrRenderAst.unMatchedAst && !ssrRenderAst.ssrStatic) {
       return this.setSSRRenderTree(prevAst)
@@ -185,6 +229,10 @@ export class PatchContext {
     let renderAst = null
 
     /**
+     * English:
+     * The current component does not match ast, but is a static component
+     *
+     * 中文：
      * 当前组件虽未匹配 ast，但是为静态组件
      */
     if (ssrRenderAst.unMatchedAst && ssrRenderAst.ssrStatic) {
@@ -194,8 +242,12 @@ export class PatchContext {
     }
 
     /**
-     * 如果当前组件已被优化成静态组件
-     * 则将当前组件的值与父组件关联
+     * English:
+     * If the current component has been optimized to be static, associate the
+     * value of the current component with the parent ast.
+     *
+     * 中文：
+     * 如果当前组件已被优化成静态组件，则将当前组件的值与父 ast 节点关联
      */
     const value = getStatisAstComponentValue(renderAst)
     if (value) {
@@ -206,6 +258,48 @@ export class PatchContext {
     this.setSSRRenderTree(prevAst)
   }
 
+  /**
+   * English:
+   * Generate a new rendering chain based on Ast's optimization information.
+   *
+   * The information for the rendering chain is stored in ssrRenderTree, which
+   * has the following structure.
+   *    {
+   *      render() {},
+   *      children: [
+   *        {
+   *          render() {},
+   *          children: []
+   *        },
+   *        {
+   *          render() {},
+   *          children: []
+   *        }
+   *      ]
+   *    }
+   * Deep priority traverses ssrRenderTree and executes the render function to
+   * render the application by optimized path.
+   *
+   * 中文：
+   * 根据 Ast 的优化信息生成全新的渲染链
+   * 渲染链的信息保存在 ssrRenderTree 中，ssrRenderTree 的结构如下所示：
+   *    {
+   *      render() {},
+   *      children: [
+   *        {
+   *          render() {},
+   *          children: []
+   *        },
+   *        {
+   *          render() {},
+   *          children: []
+   *        }
+   *      ]
+   *    }
+   * 深度优先遍历 ssrRenderTree，并执行 render 函数，即可按优化路径渲染应用
+   *
+   * @param {Object} ast
+   */
   setSSRRenderTree(ast: Object) {
     let renderStr = 'function render() {}'
     if (ast.ssrStatic && ast.ssrString !== undefined) {
@@ -277,19 +371,28 @@ export class PatchContext {
   }
 
   /**
+   * English:
+   * Optimizing the child tree of the current ast
+   *
+   * 中文：
    * 优化当前节点抽象语法树的子树
-   * @param {*} patchState
+   * @param {PatchState} patchState
    */
   reduceAstChildren(patchState: PatchState) {
     const ast = patchState.ast
     const children = getVNodeAstChildren(ast)
     /**
+     * English:
+     * If the current element node is an ssrNode node, and there is only one ssrNode child,
+     * and the child has no grandchildren, elevate the child node.
+     *
+     * 中文：
      * 如果当前元素节点为 ssrNode 节点，且只有一个 ssrNode 子节点，并且子节点没有孙节点，则把子节点提升
      */
     if (
-      children && children.elements.length === 1 && //只有一个子节点
-      isSSRNodeAst(ast) && isSSRNodeAst(children.elements[0]) && //当前元素节点为 ssrNode 节点， 子节点为 ssrNode 节点
-      children.elements[0].arguments.length === 1 // 子节点没有孙节点
+      children && children.elements.length === 1 && // Only one child node.
+      isSSRNodeAst(ast) && isSSRNodeAst(children.elements[0]) && // The current element node is an ssrNode node and the child node is an ssrNode node
+      children.elements[0].arguments.length === 1 // Child node has no grand node.
     ) {
         const node = children.elements[0].arguments[0]
         const args = ast.arguments