update docs (cocos#10796)

* update docs * update docs more * refine * refine
leqixiaozi · Apr 20, 2022 · e82cec1 · e82cec1
1 parent 019d35b
commit e82cec1
Show file tree

Hide file tree

Showing 35 changed files with 104 additions and 104 deletions.
diff --git a/cocos/2d/category.json b/cocos/2d/category.json
@@ -4,7 +4,7 @@
         "en": "2D Rendering"
     },
     "description": {
-        "zh": "2D 渲染",
-        "en": "2D Rendering"
+        "zh": "2D 渲染相关的组件与资源",
+        "en": "2D rendering related components and assets"
     }
 }
diff --git a/cocos/3d/category.json b/cocos/3d/category.json
@@ -4,7 +4,7 @@
         "en": "3D Rendering"
     },
     "description": {
-        "zh": "3D 渲染",
-        "en": "3D Rendering"
+        "zh": "3D 渲染相关的组件与资源",
+        "en": "3D rendering related components and assets"
     }
 }
diff --git a/cocos/audio/category.json b/cocos/audio/category.json
@@ -4,7 +4,7 @@
         "en": "Audio"
     },
     "description": {
-        "zh": "音频",
-        "en": "Audio"
+        "zh": "音乐是游戏中不可或缺的一部分，好的音乐能让游戏更加真实、富有沉浸感。Cocos Creator 的音频系统支持导入并播放大多数常见的音频文件格式",
+        "en": "Music is an integral part of a game, and good music makes a game more realistic and immersive. the audio system in Cocos Creator supports importing and playing most common audio file formats"
     }
 }
diff --git a/cocos/core/animation/category.json b/cocos/core/animation/category.json
@@ -4,7 +4,7 @@
         "en": "Animation"
     },
     "description": {
-        "zh": "动画",
-        "en": "Animation"
+        "zh": "Cocos Creator 内置了通用的动画系统用以实现基于关键帧的动画。除了支持标准的位移、旋转、缩放动画和帧动画之外，还支持任意组件属性和用户自定义属性的驱动，再加上可任意编辑的时间曲线和创新的移动轨迹编辑功能，能够让内容生产人员不写一行代码就制作出细腻的各种动态效果。",
+        "en": "Cocos Creator has a built-in universal animation system for implementing keyframe-based animations. In addition to standard moving, rotation, scaling and frame animations, it also supports arbitrary component properties and user-defined property drivers, plus arbitrary time curves and innovative trajectory editing, allowing content producers to create detailed dynamic effects without writing a single line of code."
     }
 }
diff --git a/cocos/core/asset-manager/asset-manager.ts b/cocos/core/asset-manager/asset-manager.ts
@@ -155,20 +155,20 @@ export class AssetManager {
 
     /**
      * @en
-     * The collection of bundle which is already loaded, you can remove cache with {{#crossLink "AssetManager/removeBundle:method"}}{{/crossLink}}
+     * The collection of bundle which is already loaded, you can remove cache with [[removeBundle]]
      *
      * @zh
-     * 已加载 bundle 的集合， 你能通过 {{#crossLink "AssetManager/removeBundle:method"}}{{/crossLink}} 来移除缓存
+     * 已加载 bundle 的集合， 你能通过 [[removeBundle]] 来移除缓存
      *
      */
     public bundles: ICache<Bundle> = bundles;
 
     /**
      * @en
-     * The collection of asset which is already loaded, you can remove cache with {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}}
+     * The collection of asset which is already loaded, you can remove cache with [[releaseAsset]]
      *
      * @zh
-     * 已加载资源的集合， 你能通过 {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}} 来移除缓存
+     * 已加载资源的集合， 你能通过 [[releaseAsset]] 来移除缓存
      */
     public assets: ICache<Asset> = assets;
 
@@ -370,10 +370,10 @@ export class AssetManager {
     /**
      * @en
      * Remove this bundle. NOTE: The asset within this bundle will not be released automatically,
-     * you can call {{#crossLink "Bundle/releaseAll:method"}}{{/crossLink}} manually before remove it if you need
+     * you can call [[Bundle.releaseAll]] manually before remove it if you need
      *
      * @zh
-     * 移除此包, 注意：这个包内的资源不会自动释放, 如果需要的话你可以在摧毁之前手动调用 {{#crossLink "Bundle/releaseAll:method"}}{{/crossLink}} 进行释放
+     * 移除此包, 注意：这个包内的资源不会自动释放, 如果需要的话你可以在摧毁之前手动调用 [[Bundle.releaseAll]] 进行释放
      *
      * @param bundle - The bundle to be removed
      *
@@ -617,10 +617,10 @@ export class AssetManager {
 
     /**
      * @en
-     * Release all unused assets. Refer to {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}} for detailed information.
+     * Release all unused assets. Refer to [[releaseAsset]] for detailed information.
      *
      * @zh
-     * 释放所有没有用到的资源。详细信息请参考 {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}}
+     * 释放所有没有用到的资源。详细信息请参考 [[releaseAsset]]
      *
      * @engineInternal
      *
@@ -633,10 +633,10 @@ export class AssetManager {
 
     /**
      * @en
-     * Release all assets. Refer to {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}} for detailed information.
+     * Release all assets. Refer to [[releaseAsset]] for detailed information.
      *
      * @zh
-     * 释放所有资源。详细信息请参考 {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}}
+     * 释放所有资源。详细信息请参考 [[releaseAsset]]
      *
      */
     public releaseAll () {

diff --git a/cocos/core/asset-manager/bundle.ts b/cocos/core/asset-manager/bundle.ts
@@ -495,14 +495,14 @@ export default class Bundle {
     /**
      * @en
      * Get cached asset within this bundle by path and type. <br>
-     * After you load asset with {{#crossLink "Bundle/load:method"}}{{/crossLink}} or {{#crossLink "Bundle/loadDir:method"}}{{/crossLink}},
+     * After you load asset with [[load]] or [[loadDir]],
      * you can acquire them by passing the path to this API.
      *
      * NOTE：The `path` and `type` parameters passed need to be the same as those passed to `Bundle.load`,
      * otherwise it may return some other resources with the same name!
      *
      * @zh
-     * 通过路径与类型获取已缓存资源。在你使用 {{#crossLink "Bundle/load:method"}}{{/crossLink}} 或者 {{#crossLink "Bundle/loadDir:method"}}{{/crossLink}} 之后，
+     * 通过路径与类型获取已缓存资源。在你使用 [[load]] 或者 [[loadDir]] 之后，
      * 你能通过传路径通过这个 API 获取到这些资源。
      *
      * 注意：传入的 path 与 type 参数需要与 `Bundle.load` 加载资源时传入的参数一致，否则可能会获取到其他同名资源
@@ -525,15 +525,15 @@ export default class Bundle {
 
     /**
      * @en
-     * Release the asset loaded by {{#crossLink "Bundle/load:method"}}{{/crossLink}} or {{#crossLink "Bundle/loadDir:method"}}{{/crossLink}}
-     * and it's dependencies. Refer to {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}} for detailed informations.
+     * Release the asset loaded by [[load]] or [[loadDir]]
+     * and it's dependencies. Refer to [[AssetManager.releaseAsset]] for detailed informations.
      *
      * NOTE：The `path` and `type` parameters passed need to be the same as those passed to `Bundle.load`,
      * otherwise it may release some other resources with the same name!
      *
      * @zh
-     * 释放通过 {{#crossLink "Bundle/load:method"}}{{/crossLink}} 或者 {{#crossLink "Bundle/loadDir:method"}}{{/crossLink}} 加载的资源。
-     * 详细信息请参考 {{#crossLink "AssetManager/releaseAsset:method"}}{{/crossLink}}
+     * 释放通过 [[load]] 或者 [[loadDir]] 加载的资源。
+     * 详细信息请参考 [[AssetManager.releaseAsset]]
      *
      * 注意：传入的 path 与 type 参数需要与 `Bundle.load` 加载资源时传入的参数一致，否则可能会释放到其他同名资源
      *
@@ -554,10 +554,10 @@ export default class Bundle {
 
     /**
      * @en
-     * Release all unused assets within this bundle. Refer to {{#crossLink "AssetManager/releaseAll:method"}}{{/crossLink}} for detailed informations.
+     * Release all unused assets within this bundle. Refer to [[AssetManager.releaseAll]] for detailed informations.
      *
      * @zh
-     * 释放此包中的所有没有用到的资源。详细信息请参考 {{#crossLink "AssetManager/releaseAll:method"}}{{/crossLink}}
+     * 释放此包中的所有没有用到的资源。详细信息请参考 [[AssetManager.releaseAll]]
      *
      * @private
      *
@@ -577,10 +577,10 @@ export default class Bundle {
 
     /**
      * @en
-     * Release all assets within this bundle. Refer to {{#crossLink "AssetManager/releaseAll:method"}}{{/crossLink}} for detailed informations.
+     * Release all assets within this bundle. Refer to [[AssetManager.releaseAll]] for detailed information.
      *
      * @zh
-     * 释放此包中的所有资源。详细信息请参考 {{#crossLink "AssetManager/releaseAll:method"}}{{/crossLink}}
+     * 释放此包中的所有资源。详细信息请参考 [[AssetManager.releaseAll]]
      *
      * @example
      * // release all asset within bundle1

diff --git a/cocos/core/asset-manager/category.json b/cocos/core/asset-manager/category.json
@@ -4,7 +4,7 @@
         "en": "Asset"
     },
     "description": {
-        "zh": "资源",
-        "en": "Asset"
+        "zh": "资源是游戏中的重要组成部分，Cocos Creator 支持导入大量类型的资源，并允许开发者将该资源运用在游戏中",
+        "en": "Assets are an important part of the game, and Cocos Creator supports importing a large number of types of resources and allows developers to use that resource in the game"
     }
 }
diff --git a/cocos/core/asset-manager/deprecated.ts b/cocos/core/asset-manager/deprecated.ts
@@ -87,8 +87,8 @@ type LoadCompleteCallback<T> = (error: Error | null, asset: T) => void;
 type LoadDirCompleteCallback<T> = (error: Error | null, asset: T[], urls: string[]) => void;
 
 /**
- * @en Loader for resource loading process. The engine automatically initialize its singleton object {{loader}}.
- * @zh 资源加载管理器，引擎会自动创建一个单例对象 {{loader}}。
+ * @en Loader for resource loading process. The engine automatically initialize its singleton object [[loader]].
+ * @zh 资源加载管理器，引擎会自动创建一个单例对象 [[loader]]。
  *
  * @class loader
  * @static
@@ -97,8 +97,8 @@ type LoadDirCompleteCallback<T> = (error: Error | null, asset: T[], urls: string
 export class CCLoader {
     /**
      * @en The default progression callback during the loading process,
-     * if no progression callback is passed to {{load}} function, then this default callback will be used.
-     * @zh Loader 默认的进度回调函数，如果在调用 {{load}} 函数时没有指定进度回调函数的话，会调用默认进度回调函数。
+     * if no progression callback is passed to [[load]] function, then this default callback will be used.
+     * @zh Loader 默认的进度回调函数，如果在调用 [[load]] 函数时没有指定进度回调函数的话，会调用默认进度回调函数。
      *
      * @deprecated since v3.0, loader.onProgress is deprecated, please transfer onProgress to API as a parameter
      */
@@ -631,7 +631,7 @@ export class CCLoader {
      * Release the content of an asset or an array of assets by uuid.<br>
      * This method will not only remove the cache of the asset in loader, but also clean up its content.<br>
      * For example, if you release a texture, the texture asset and its gl texture data will be freed up.<br>
-     * In complexe project, you can use this function with [[getDependsRecursively]] to free up memory in critical circumstances.<br>
+     * In complex project, you can use this function with [[getDependsRecursively]] to free up memory in critical circumstances.<br>
      * Notice, this method may cause the texture to be unusable, if there are still other nodes use the same texture, they may turn to black
      * and report gl errors.<br>
      * @zh
@@ -676,8 +676,8 @@ export class CCLoader {
     }
 
     /**
-     * @en Release the asset by its object. Refer to {{release}} for detailed informations.
-     * @zh 通过资源对象自身来释放资源。详细信息请参考 {{release}}
+     * @en Release the asset by its object. Refer to [[release]] for detailed informations.
+     * @zh 通过资源对象自身来释放资源。详细信息请参考 [[release]]
      * @param asset The asset to be released
      *
      * @deprecated since v3.0 loader.releaseAsset is deprecated, please use assetManager.releaseAsset instead
@@ -687,8 +687,8 @@ export class CCLoader {
     }
 
     /**
-     * @en Release the asset loaded by {{loadRes}}. Refer to {{release}} for detailed informations.
-     * @zh 释放通过 {{loadRes}} 加载的资源。详细信息请参考 {{release}}
+     * @en Release the asset loaded by [[loadRes]]. Refer to [[release]] for detailed informations.
+     * @zh 释放通过 [[loadRes]] 加载的资源。详细信息请参考 [[release]]
      * @param res The asset url, it should be related path without extension to the `resources` folder.
      * @param type If type is provided, the asset for correspond type will be returned
      *
@@ -700,8 +700,8 @@ export class CCLoader {
 
     /**
      *
-     * @en Resource all assets. Refer to {{release}} for detailed informations.
-     * @zh 释放所有资源。详细信息请参考 {{release}}
+     * @en Resource all assets. Refer to [[release]] for detailed informations.
+     * @zh 释放所有资源。详细信息请参考 [[release]]
      *
      * @deprecated since v3.0 loader.releaseAll is deprecated, please use assetManager.releaseAll instead
      */
@@ -714,10 +714,10 @@ export class CCLoader {
      * @en Removes an completed item in pipeline.
      * It will only remove the cache in the pipeline or loader, its dependencies won't be released.
      * cc.loader provided another method to completely cleanup the resource and its dependencies,
-     * please refer to {{Loader.release}}
+     * please refer to [[release]]
      * @zh 移除指定的已完成 item。
      * 这将仅仅从 pipeline 或者 loader 中删除其缓存，并不会释放它所依赖的资源。
-     * cc.loader 中提供了另一种删除资源及其依赖的清理方法，请参考 {{Loader.release}}
+     * cc.loader 中提供了另一种删除资源及其依赖的清理方法，请参考 [[release]]
      * @param id The id of the item
      * @return succeed or not
      *
@@ -736,14 +736,14 @@ export class CCLoader {
      * will not be affected by that option, remain not released by default.<br>
      * Use this API to change the default behavior on a single asset, to force preserve or release specified asset when scene switching.<br>
      * <br>
-     * See: {{setAutoReleaseRecursively}}, {{isAutoRelease}}
+     * See: [[setAutoReleaseRecursively]], [[isAutoRelease]]
      * @zh
      * 设置当场景切换时是否自动释放资源。<br>
      * 默认情况下，当加载新场景时，旧场景的资源根据旧场景是否勾选“Auto Release Assets”，将会被释放或者保留。<br>
      * 而使用 `loader.loadRes` 或 `loader.loadResDir` 动态加载的资源，则不受场景设置的影响，默认不自动释放。<br>
      * 使用这个 API 可以在单个资源上改变这个默认行为，强制在切换场景时保留或者释放指定资源。<br>
      * <br>
-     * 参考：{{setAutoReleaseRecursively}}，{{isAutoRelease}}
+     * 参考：[[setAutoReleaseRecursively]]，[[isAutoRelease]]
      *
      * @example
      * ```typescript
@@ -774,14 +774,14 @@ export class CCLoader {
      * Use this API to change the default behavior on the specified asset and its recursively referenced assets,
      * to force preserve or release specified asset when scene switching.<br>
      * <br>
-     * See: {{setAutoRelease}}, {{isAutoRelease}}
+     * See: [[setAutoRelease]], [[isAutoRelease]]
      * @zh
      * 设置当场景切换时是否自动释放资源及资源引用的其它资源。<br>
      * 默认情况下，当加载新场景时，旧场景的资源根据旧场景是否勾选“Auto Release Assets”，将会被释放或者保留。<br>
      * 而使用 `loader.loadRes` 或 `loader.loadResDir` 动态加载的资源，则不受场景设置的影响，默认不自动释放。<br>
      * 使用这个 API 可以在指定资源及资源递归引用到的所有资源上改变这个默认行为，强制在切换场景时保留或者释放指定资源。<br>
      * <br>
-     * 参考：{{setAutoRelease}}，{{isAutoRelease}}
+     * 参考：[[setAutoRelease]]，[[isAutoRelease]]
      *
      * @example
      * ```typescript
@@ -809,10 +809,10 @@ export class CCLoader {
     /**
      * @en Returns whether the asset is configured as auto released, despite how "Auto Release Assets" property is set on scene asset.<br>
      * <br>
-     * See: {{setAutoRelease}}, {{setAutoReleaseRecursively}}
+     * See: [[setAutoRelease]], [[setAutoReleaseRecursively]]
      * @zh 返回指定的资源是否有被设置为自动释放，不论场景的“Auto Release Assets”如何设置。<br>
      * <br>
-     * 参考：{{setAutoRelease}}，{{setAutoReleaseRecursively}}
+     * 参考：[[setAutoRelease]]，[[setAutoReleaseRecursively]]
      *
      * @method isAutoRelease
      * @param {Asset|String} asset - asset object or the raw asset's url

diff --git a/cocos/core/assets/category.json b/cocos/core/assets/category.json
@@ -4,7 +4,7 @@
         "en": "Asset"
     },
     "description": {
-        "zh": "资源",
-        "en": "Asset"
+        "zh": "资源是游戏中的重要组成部分，Cocos Creator 支持导入不同类型的资源，并允许开发者将该资源运用在游戏中",
+        "en": "Assets are crucial for game content, Cocos Creator supports importing various types of assets and allows developers to use these resources in the game logic in runtime"
     }
 }
diff --git a/cocos/core/category.json b/cocos/core/category.json
@@ -4,7 +4,7 @@
         "en": "Core"
     },
     "description": {
-        "zh": "核心模块",
-        "en": "Core"
+        "zh": "Cocos Creator 核心功能。",
+        "en": "Cocos Creator core functionalities."
     }
 }
diff --git a/cocos/core/data/decorators/editable.ts b/cocos/core/data/decorators/editable.ts
@@ -74,7 +74,7 @@ export const executeInEditMode: ClassDecorator & ((yes?: boolean) => ClassDecora
 export const menu: (path: string) => ClassDecorator =    DEV ? makeEditorClassDecoratorFn('menu') : emptyDecoratorFn;
 
 /**
- * @en When {{executeInEditMode}} is set, this decorator will decide when a node with the component is on focus whether the editor should running in high FPS mode.
+ * @en When [[executeInEditMode]] is set, this decorator will decide when a node with the component is on focus whether the editor should running in high FPS mode.
  * @zh 当指定了 "executeInEditMode" 以后，playOnFocus 可以在选中当前组件所在的节点时，提高编辑器的场景刷新频率到 60 FPS，否则场景就只会在必要的时候进行重绘。
  * @example
  * ```ts

diff --git a/cocos/core/data/decorators/property.ts b/cocos/core/data/decorators/property.ts
@@ -58,7 +58,7 @@ export function property (options?: IPropertyOptions): LegacyPropertyDecorator;
  * @en Declare as a CCClass property with the property type
  * @zh 标注属性为 cc 属性。<br/>
  * 等价于`@property({type})`。
- * @param type A {{ccclass}} type or a {{ValueType}}
+ * @param type A [[ccclass]] type or a [[ValueType]]
  */
 export function property (type: PropertyType): LegacyPropertyDecorator;
 

diff --git a/cocos/core/gfx/category.json b/cocos/core/gfx/category.json
@@ -4,7 +4,7 @@
         "en": "GFX"
     },
     "description": {
-        "zh": "图形后端抽象",
-        "en": "GFX"
+        "zh": "图形后端抽象类，用于抹平不同渲染后端 API 差异",
+        "en": "Graphical backend abstraction classes for unifying APIs of different rendering backends"
     }
 }
diff --git a/cocos/core/math/category.json b/cocos/core/math/category.json
@@ -4,7 +4,7 @@
         "en": "Math"
     },
     "description": {
-        "zh": "数学",
-        "en": "Math"
+        "zh": "数学库，包含 2D 与 3D 维度下的向量和矩阵运算，与其他一些相关数学类型",
+        "en": "Mathematical library, including vector and matrix operations in two dimensions and three dimensions, also including some other mathematic related classes."
     }
 }