From 72d7613e9c2cf1be1be4a17fe06ec43b626c9ec1 Mon Sep 17 00:00:00 2001
From: 06wj <06wj@163.com>
Date: Tue, 1 Sep 2020 15:45:27 +0800
Subject: [PATCH] docs: update jsdoc comments

---
 package.json                     |  2 +-
 src/camera/OrthographicCamera.js |  7 ++++
 src/camera/PerspectiveCamera.js  |  7 +++-
 src/core/Class.js                | 16 +++----
 src/core/Mesh.js                 |  5 ++-
 src/core/Stage.js                | 26 +++++++-----
 src/geometry/BoxGeometry.js      |  9 +++-
 src/geometry/PlaneGeometry.js    |  5 +++
 src/geometry/SphereGeometry.js   |  6 ++-
 src/light/AmbientLight.js        |  4 +-
 src/light/DirectionalLight.js    |  4 ++
 src/light/PointLight.js          |  4 ++
 src/light/SpotLight.js           |  7 ++++
 src/material/BasicMaterial.js    | 14 ++++++-
 src/material/PBRMaterial.js      | 25 +++++++++--
 src/utils/Ticker.js              | 72 ++++++++++++++++++++++++++++++++
 16 files changed, 181 insertions(+), 32 deletions(-)

diff --git a/package.json b/package.json
index c4cbc2ef..9a890e92 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,7 @@
   "devDependencies": {
     "@babel/core": "^7.1.0",
     "@babel/preset-env": "^7.1.0",
-    "@hilo/tsd-jsdoc": "^0.1.0",
+    "@hilo/tsd-jsdoc": "^0.1.5",
     "babel-loader": "^8.0.2",
     "conventional-changelog-cli": "^2.0.31",
     "del": "^3.0.0",
diff --git a/src/camera/OrthographicCamera.js b/src/camera/OrthographicCamera.js
index 2be94d26..d58ac58d 100644
--- a/src/camera/OrthographicCamera.js
+++ b/src/camera/OrthographicCamera.js
@@ -121,6 +121,13 @@ const OrthographicCamera = Class.create(/** @lends OrthographicCamera.prototype
     /**
      * @constructs
      * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {number} [params.left=1]
+     * @param {number} [params.right=1]
+     * @param {number} [params.top=1]
+     * @param {number} [params.bottom=1]
+     * @param {number} [params.near=0.1]
+     * @param {number} [params.far=1]
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         OrthographicCamera.superclass.constructor.call(this, params);
diff --git a/src/camera/PerspectiveCamera.js b/src/camera/PerspectiveCamera.js
index bc46f53a..fb799708 100644
--- a/src/camera/PerspectiveCamera.js
+++ b/src/camera/PerspectiveCamera.js
@@ -93,7 +93,12 @@ const PerspectiveCamera = Class.create(/** @lends PerspectiveCamera.prototype */
 
     /**
      * @constructs
-     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {number} [params.fov=50] 相机视野大小，角度制
+     * @param {number} [params.near=0.1] 相机视锥体近平面z
+     * @param {number} [params.far=null] 相机视锥体远平面z，null 时为无限远
+     * @param {number} [params.aspect=1] 宽高比
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         PerspectiveCamera.superclass.constructor.call(this, params);
diff --git a/src/core/Class.js b/src/core/Class.js
index 0c00bc8f..6eb80968 100644
--- a/src/core/Class.js
+++ b/src/core/Class.js
@@ -11,14 +11,10 @@ export default Class;
 /**
  * @memberOf Class
  * @method create
- * @param {ClassProperty | Object} props
- */
-
-/**
- * 类属性
- * @interface ClassProperty
- * @property {Object} [Statics] 静态属性
- * @property {Object} [Extends] 继承
- * @property {Object} [Mixes] mixes
- * @property {Function} [constructor] 构造函数
+ * @param {Object} params 类属性
+ * @param {Object} [params.Statics] 静态属性
+ * @param {Object} [params.Extends] 继承
+ * @param {Object} [params.Mixes] mixes
+ * @param {Function} [params.constructor] 构造函数
+ * @param {any} [params.[value:string]] 其它属性
  */
diff --git a/src/core/Mesh.js b/src/core/Mesh.js
index b8462b9d..2db51be3 100644
--- a/src/core/Mesh.js
+++ b/src/core/Mesh.js
@@ -54,7 +54,10 @@ const Mesh = Class.create(/** @lends Mesh.prototype */ {
     frustumTest: true,
     /**
      * @constructs
-     * @param {object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {Object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {Geometry} [params.geometry] 几何体
+     * @param {Material} [params.material] 材质
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         Mesh.superclass.constructor.call(this, params);
diff --git a/src/core/Stage.js b/src/core/Stage.js
index 0e948c42..5652098d 100644
--- a/src/core/Stage.js
+++ b/src/core/Stage.js
@@ -72,19 +72,23 @@ const Stage = Class.create(/** @lends Stage.prototype */ {
      * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性，所有属性会透传给 Renderer。
      * @param {HTMLElement} [params.container] stage的容器, 如果有，会把canvas加进container里。
      * @param {HTMLCanvasElement} [params.canvas] stage的canvas，不传会自动创建。
-     * @param {Number} [params.pixelRatio=根据设备自动判断] 像素密度。
+     * @param {Camera} [params.camera] stage的摄像机。
+     * @param {number} [params.width=innerWidth] stage的宽，默认网页宽度
+     * @param {number} [params.height=innerHeight] stage的高，默认网页高度
+     * @param {number} [params.pixelRatio=根据设备自动判断] 像素密度。
      * @param {Color} [params.clearColor=new Color(1, 1, 1, 1)] 背景色。
-     * @param {Boolean} [params.useFramebuffer=false] 是否使用Framebuffer，有后处理需求时需要。
+     * @param {boolean} [params.useFramebuffer=false] 是否使用Framebuffer，有后处理需求时需要。
      * @param {Object} [params.framebufferOption={}] framebufferOption Framebuffer的配置，useFramebuffer为true时生效。
-     * @param {Boolean} [params.useLogDepth=false] 是否使用对数深度，处理深度冲突。
-     * @param {Boolean} [params.alpha=false] 是否背景透明。
-     * @param {Boolean} [params.depth=true] 是否需要深度缓冲区。
-     * @param {Boolean} [params.stencil=false] 是否需要模版缓冲区。
-     * @param {Boolean} [params.antialias=true] 是否抗锯齿。
-     * @param {Boolean} [params.premultipliedAlpha=true] 是否需要 premultipliedAlpha。
-     * @param {Boolean} [params.preserveDrawingBuffer=false] 是否需要 preserveDrawingBuffer。
-     * @param {Boolean} [params.failIfMajorPerformanceCaveat=false] 是否需要 failIfMajorPerformanceCaveat。
-     * @param {Boolean} [params.gameMode=false] 是否开启游戏模式，UC 浏览器专用
+     * @param {boolean} [params.useLogDepth=false] 是否使用对数深度，处理深度冲突。
+     * @param {boolean} [params.alpha=false] 是否背景透明。
+     * @param {boolean} [params.depth=true] 是否需要深度缓冲区。
+     * @param {boolean} [params.stencil=false] 是否需要模版缓冲区。
+     * @param {boolean} [params.antialias=true] 是否抗锯齿。
+     * @param {boolean} [params.premultipliedAlpha=true] 是否需要 premultipliedAlpha。
+     * @param {boolean} [params.preserveDrawingBuffer=false] 是否需要 preserveDrawingBuffer。
+     * @param {boolean} [params.failIfMajorPerformanceCaveat=false] 是否需要 failIfMajorPerformanceCaveat。
+     * @param {boolean} [params.gameMode=false] 是否开启游戏模式，UC 浏览器专用
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         if (!params.width) {
diff --git a/src/geometry/BoxGeometry.js b/src/geometry/BoxGeometry.js
index 0accc302..75e03c81 100644
--- a/src/geometry/BoxGeometry.js
+++ b/src/geometry/BoxGeometry.js
@@ -63,7 +63,14 @@ const BoxGeometry = Class.create(/** @lends BoxGeometry.prototype */ {
     depthSegments: 1,
     /**
      * @constructs
-     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {number} [params.width=1] box的宽度
+     * @param {number} [params.height=1] box的高度
+     * @param {number} [params.depth=1] box的深度
+     * @param {number} [params.widthSegments=1] 水平分割面的数量
+     * @param {number} [params.heightSegments=1] 垂直分割面的数量
+     * @param {number} [params.depthSegments=1] 深度分割面的数量
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         BoxGeometry.superclass.constructor.call(this, params);
diff --git a/src/geometry/PlaneGeometry.js b/src/geometry/PlaneGeometry.js
index efd62056..407f6d98 100644
--- a/src/geometry/PlaneGeometry.js
+++ b/src/geometry/PlaneGeometry.js
@@ -54,6 +54,11 @@ const PlaneGeometry = Class.create(/** @lends PlaneGeometry.prototype */ {
     /**
      * @constructs
      * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {number} [params.width=1] 宽度
+     * @param {number} [params.height=1] 高度
+     * @param {number} [params.widthSegments=1] 水平分割面的数量
+     * @param {number} [params.heightSegments=1] 垂直分割面的数量
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         PlaneGeometry.superclass.constructor.call(this, params);
diff --git a/src/geometry/SphereGeometry.js b/src/geometry/SphereGeometry.js
index 76fb6994..7775300b 100644
--- a/src/geometry/SphereGeometry.js
+++ b/src/geometry/SphereGeometry.js
@@ -40,7 +40,11 @@ const SphereGeometry = Class.create(/** @lends SphereGeometry.prototype */ {
     widthSegments: 32,
     /**
      * @constructs
-     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {number} [params.radius=1] 半径
+     * @param {number} [params.heightSegments=16] 垂直分割面的数量
+     * @param {number} [params.widthSegments=32] 水平分割面的数量
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         SphereGeometry.superclass.constructor.call(this, params);
diff --git a/src/light/AmbientLight.js b/src/light/AmbientLight.js
index 88320b98..fbaa6224 100644
--- a/src/light/AmbientLight.js
+++ b/src/light/AmbientLight.js
@@ -23,8 +23,10 @@ const AmbientLight = Class.create(/** @lends AmbientLight.prototype */{
     autoUpdateWorldMatrix: false,
     /**
      * @constructs
-     * @override
      * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Color} [params.color=new Color(1, 1, 1)] 光颜色
+     * @param {number} [params.amount=1] 光强度
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         AmbientLight.superclass.constructor.call(this, params);
diff --git a/src/light/DirectionalLight.js b/src/light/DirectionalLight.js
index e7b0525f..ab8c7590 100644
--- a/src/light/DirectionalLight.js
+++ b/src/light/DirectionalLight.js
@@ -27,6 +27,10 @@ const DirectionalLight = Class.create(/** @lends DirectionalLight.prototype */ {
     /**
      * @constructs
      * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Color} [params.color=new Color(1, 1, 1)] 光颜色
+     * @param {number} [params.amount=1] 光强度
+     * @param {Vector3} [params.direction=new Vector3(0, 0, 1)] 光方向
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         /**
diff --git a/src/light/PointLight.js b/src/light/PointLight.js
index 101c750b..d0f93051 100644
--- a/src/light/PointLight.js
+++ b/src/light/PointLight.js
@@ -22,6 +22,10 @@ const PointLight = Class.create(/** @lends PointLight.prototype */ {
     /**
      * @constructs
      * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Color} [params.color=new Color(1, 1, 1)] 光颜色
+     * @param {number} [params.amount=1] 光强度
+     * @param {number} [params.range=0] 光照范围, 0 时代表光照范围无限大。
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         PointLight.superclass.constructor.call(this, params);
diff --git a/src/light/SpotLight.js b/src/light/SpotLight.js
index 5e47a532..dd698892 100644
--- a/src/light/SpotLight.js
+++ b/src/light/SpotLight.js
@@ -61,6 +61,13 @@ const SpotLight = Class.create(/** @lends SpotLight.prototype */{
     /**
      * @constructs
      * @param {Object} [params] 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Color} [params.color=new Color(1, 1, 1)] 光颜色
+     * @param {number} [params.amount=1] 光强度
+     * @param {number} [params.range=0] 光照范围, 0 时代表光照范围无限大。
+     * @param {Vector3} [params.direction=new Vector3(0, 0, 1)] 光方向
+     * @param {number} [params.cutoff=12.5] 切光角(角度)，落在这个角度之内的光亮度为1
+     * @param {number} [params.outerCutoff=17.5] 外切光角(角度)，在切光角合外切光角之间的光亮度渐变到0
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         /**
diff --git a/src/material/BasicMaterial.js b/src/material/BasicMaterial.js
index 302d12d1..60714db0 100644
--- a/src/material/BasicMaterial.js
+++ b/src/material/BasicMaterial.js
@@ -92,7 +92,19 @@ const BasicMaterial = Class.create(/** @lends BasicMaterial.prototype */ {
     usedUniformVectors: 11,
     /**
      * @constructs
-     * @param {object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {Object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {string} [params.lightType=BLINN-PHONG] 光照类型，支持: NONE, PHONG, BLINN-PHONG, LAMBERT
+     * @param {Texture|Color} [params.diffuse=new Color(.5, .5, .5)] 漫反射贴图，或颜色
+     * @param {Texture|Color} [params.ambient] 环境光贴图，或颜色
+     * @param {Texture|Color} [params.specular=new Color(1, 1, 1)] 镜面贴图，或颜色
+     * @param {Texture|Color} [params.emission=new Color(0, 0, 0)] 放射光贴图，或颜色
+     * @param {Texture} [params.specularEnvMap] 环境贴图
+     * @param {Matrix4} [params.specularEnvMatrix] 环境贴图变化矩阵，如旋转等
+     * @param {number} [params.reflectivity=0] 反射率
+     * @param {number} [params.refractRatio=0] 折射比率
+     * @param {number} [params.refractivity=0] 折射率
+     * @param {number} [params.shininess=32] 高光发光值
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         this.diffuse = new Color(.5, .5, .5);
diff --git a/src/material/PBRMaterial.js b/src/material/PBRMaterial.js
index df0c87b5..1a37be0c 100644
--- a/src/material/PBRMaterial.js
+++ b/src/material/PBRMaterial.js
@@ -26,7 +26,7 @@ const PBRMaterial = Class.create(/** @lends PBRMaterial.prototype */ {
     className: 'PBRMaterial',
 
     /**
-     * 光照类型，只能为 PBR
+     * 光照类型，只能为 PBR 或 NONE
      * @default PBR
      * @readOnly
      * @type {string}
@@ -143,7 +143,7 @@ const PBRMaterial = Class.create(/** @lends PBRMaterial.prototype */ {
     brdfLUT: null,
 
     /**
-     * 环境反射(Specular IBL)贴图
+     * 环境反射(Specular IBL)贴图强度
      * @default 1
      * @type {Number}
      */
@@ -165,7 +165,7 @@ const PBRMaterial = Class.create(/** @lends PBRMaterial.prototype */ {
 
     /**
      * 放射光贴图(sRGB 空间)，或颜色
-     * @default Color(0, 0, 0)
+     * @default null
      * @type {Texture|Color}
      */
     emission: null,
@@ -203,7 +203,24 @@ const PBRMaterial = Class.create(/** @lends PBRMaterial.prototype */ {
 
     /**
      * @constructs
-     * @param {object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {Object} [params] 初始化参数，所有params都会复制到实例上
+     * @param {string} [params.lightType=PBR] 光照类型，只能为 PBR 或 NONE
+     * @param {Color} [params.baseColor=new Color(1, 1, 1)] 基础颜色
+     * @param {Texture} [params.baseColorMap] 基础颜色贴图(sRGB空间)
+     * @param {number} [params.metallic=1] 金属度
+     * @param {Texture} [params.metallicMap] 金属度贴图
+     * @param {number} [params.roughness=1] 粗糙度
+     * @param {Texture} [params.roughnessMap] 粗糙度贴图
+     * @param {Texture} [params.occlusionMap] 环境光遮蔽贴图
+     * @param {number} [params.occlusionStrength=1] 环境光遮蔽强度
+     * @param {Texture|Color} [params.emission] 放射光贴图(sRGB 空间)，或颜色
+     * @param {Texture} [params.diffuseEnvMap] 漫反射辐照(Diffuse IBL)贴图
+     * @param {SphericalHarmonics3} [params.diffuseEnvSphereHarmonics3] 漫反射 SphericalHarmonics3
+     * @param {number} [params.diffuseEnvIntensity=1] 漫反射强度
+     * @param {Texture} [params.specularEnvMap] 环境反射(Specular IBL)贴图
+     * @param {Texture} [params.brdfLUT] BRDF贴图，跟环境反射贴图一起使用
+     * @param {number} [params.specularEnvIntensity=1] 环境反射(Specular IBL)贴图强度
+     * @param {any} [params.[value:string]] 其它属性
      */
     constructor(params) {
         this.baseColor = new Color(1, 1, 1);
diff --git a/src/utils/Ticker.js b/src/utils/Ticker.js
index 3ca966be..921b9f45 100644
--- a/src/utils/Ticker.js
+++ b/src/utils/Ticker.js
@@ -5,4 +5,76 @@
  */
 import Ticker from 'hilojs/util/Ticker';
 
+/**
+ * 添加定时器对象。定时器对象必须实现 tick 方法。
+ * @memberOf Ticker.prototype
+ * @method addTick
+ * @param {Object} tickObject
+ */
+
+/**
+ * 删除定时器对象。
+ * @memberOf Ticker.prototype
+ * @method removeTick
+ * @param {Object} tickObject
+ */
+
+/**
+ * 开始计时器
+ * @memberOf Ticker.prototype
+ * @method start
+ */
+
+/**
+ * 停止计时器
+ * @memberOf Ticker.prototype
+ * @method stop
+ */
+
+/**
+ * 暂停计时器
+ * @memberOf Ticker.prototype
+ * @method pause
+ */
+
+/**
+ * 恢复计时器
+ * @memberOf Ticker.prototype
+ * @method resume
+ */
+
+/**
+ * 延迟指定的时间后调用回调, 类似setTimeout
+ * @memberOf Ticker.prototype
+ * @method timeout
+ * @param {Function} callback
+ * @param {number} duration 时间周期，单位毫秒
+ * @returns {Object} tickObject 定时器对象
+ */
+
+/**
+ * 指定的时间周期来调用函数, 类似setInterval
+ * @memberOf Ticker.prototype
+ * @method interval
+ * @param {Function} callback
+ * @param {number} duration 时间周期，单位毫秒
+ * @returns {Object} tickObject 定时器对象
+ */
+
+/**
+ * 下次tick时回调
+ * @memberOf Ticker.prototype
+ * @method nextTick
+ * @param {Function} callback
+ * @returns {Object} tickObject 定时器对象
+ */
+
+/**
+ * 获得测定的运行时帧率。
+ * @memberOf Ticker.prototype
+ * @method getMeasuredFPS
+ * @returns {number}
+ */
+
+
 export default Ticker;