build: Auto generate the Typescript Definition file (hiloteam#20)

* build: init tsd jsdoc

* docs: update jsdoc

* use hilo/tsd-jsdoc

* fix types

* build .d.ts

* eslint-fix

* more tsd fix

* fix types

* fix geometrydata tsd

* fix geo tsd

* fix light tsd

* fix tsd

* fix types

* fix tsd

* fix type

* fix tsd

* fix typo

Author: 06wj

gulpfile.js

@@ -23,6 +23,35 @@ const testTask = () => {
         }));
 };
 
+const hilo3dTSDHeader = `export = hilo3d;
+export as namespace hilo3d;
+declare namespace hilo3d {
+
+type TypedArray =
+    | Int8Array
+    | Uint8Array
+    | Uint8ClampedArray
+    | Int16Array
+    | Uint16Array
+    | Int32Array
+    | Uint32Array
+    | Float32Array
+    | Float64Array;
+
+`;
+
+const hilo3dTSDFooter = `
+
+}
+`;
+
+const addHilo3dTSD = () => {
+    return src('./types/index.d.ts')
+        .pipe(replace(/^/, hilo3dTSDHeader))
+        .pipe(replace(/$/, hilo3dTSDFooter))
+        .pipe(dest('types'));
+};
+
 const readmeTask = () => {
     return src(['./README.md', './README_ZH.md'])
         .pipe(replace(/Hilo3d\/[\d\.]+\/Hilo3d\.js/g, `Hilo3d/${pkg.version}/Hilo3d.js`))
@@ -35,4 +64,5 @@ const watchTask = () => {
 
 exports.test = series(testBuildTask, testTask);
 exports.watch = series(testBuildTask, testTask, watchTask);
-exports.readme = readmeTask;
+exports.readme = readmeTask;
+exports.addHilo3dTSD = addHilo3dTSD;

package.json

@@ -12,6 +12,7 @@
     "build": " webpack",
     "release": "tnpm update && webpack -p",
     "doc": "gulp readme && jsdoc -c doc.conf.json",
+    "doc-tsd": "jsdoc -c tsd-doc.conf.json && gulp addHilo3dTSD",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r",
     "eslint-fix": "eslint --fix ./src",
     "seinjs-dev": "webpack --watch --env.development --seinjs",
@@ -40,6 +41,7 @@
   "devDependencies": {
     "@babel/core": "^7.1.0",
     "@babel/preset-env": "^7.1.0",
+    "@hilo/tsd-jsdoc": "^0.1.0",
     "babel-loader": "^8.0.2",
     "conventional-changelog-cli": "^2.0.31",
     "del": "^3.0.0",
@@ -54,7 +56,7 @@
     "gulp-concat": "^2.6.1",
     "gulp-replace": "^1.0.0",
     "gulp-uitest": "^1.0.0",
-    "jsdoc": "^3.5.5",
+    "jsdoc": "^3.6.4",
     "mocha": "^5.2.0",
     "raw-loader": "^0.5.1",
     "should": "^13.2.3",

src/animation/Animation.js

@@ -16,8 +16,8 @@ const Animation = Class.create(/** @lends Animation.prototype */{
         /**
          * tick
          * @memberOf Animation
-         * @static
-         * @param  {Number} dt 一帧时间
+         * @method tick
+         * @param {Number} dt 一帧时间
          */
         tick(dt) {
             this._anims.forEach(anim => anim.tick(dt));
@@ -111,7 +111,7 @@ const Animation = Class.create(/** @lends Animation.prototype */{
     validAnimationIds: null,
     /**
      * @constructs
-     * @param {Object} parmas 创建对象的属性参数。可包含此类的所有属性。
+     * @param {Object} [parmas] 创建对象的属性参数。可包含此类的所有属性。
      */
     constructor(parmas) {
         /**
@@ -138,7 +138,7 @@ const Animation = Class.create(/** @lends Animation.prototype */{
      * @param {string} name 剪辑名字
      * @param {number} start 动画开始时间
      * @param {number} end 动画结束时间
-     * @param {Array.<AnimationState>} animStatesList 动画帧列表
+     * @param {AnimationStates[]} animStatesList 动画帧列表
      */
     addClip(name, start, end, animStatesList) {
         this.clips[name] = {
@@ -191,6 +191,10 @@ const Animation = Class.create(/** @lends Animation.prototype */{
             }, false);
         }
     },
+    /**
+     * tick
+     * @param  {Number} dt
+     */
     tick(dt) {
         if (this.paused) {
             return;

src/camera/Camera.js

@@ -36,7 +36,7 @@ const Camera = Class.create(/** @lends Camera.prototype */ {
 
     /**
      * @constructs
-     * @param {object} params 创建对象的属性参数。可包含此类的所有属性。
+     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
      */
     constructor(params) {
         /**

src/camera/OrthographicCamera.js

@@ -120,7 +120,7 @@ const OrthographicCamera = Class.create(/** @lends OrthographicCamera.prototype
 
     /**
      * @constructs
-     * @param {object} params 创建对象的属性参数。可包含此类的所有属性。
+     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
      */
     constructor(params) {
         OrthographicCamera.superclass.constructor.call(this, params);

src/camera/PerspectiveCamera.js

@@ -59,7 +59,7 @@ const PerspectiveCamera = Class.create(/** @lends PerspectiveCamera.prototype */
 
     _fov: 50,
     /**
-     * 相机视野大小，角度
+     * 相机视野大小，角度制
      * @default 50
      * @type {number}
      */
@@ -93,7 +93,7 @@ const PerspectiveCamera = Class.create(/** @lends PerspectiveCamera.prototype */
 
     /**
      * @constructs
-     * @param {object} params 创建对象的属性参数。可包含此类的所有属性。
+     * @param {object} [params] 创建对象的属性参数。可包含此类的所有属性。
      */
     constructor(params) {
         PerspectiveCamera.superclass.constructor.call(this, params);

src/constants/index.js

@@ -2,6 +2,13 @@ import webgl from './webgl';
 import webglExtensions from './webglExtensions';
 import * as Hilo from './Hilo';
 
+/**
+ * WebGL, WebGL extensions 枚举值
+ * @constant
+ * @type {Object}
+ * @example
+ * Hilo3d.constants.LINEAR_MIPMAP_NEAREST
+ */
 const constants = {
     webgl,
     webglExtensions,
@@ -10,7 +17,3 @@ const constants = {
 Object.assign(constants, webgl, webglExtensions, Hilo);
 
 export default constants;
-/**
- * Hilo3d 枚举值，可通过 Hilo3d.constants.xxx 获取
- * @typedef {Number} GLenum
- */

src/core/Class.js

@@ -6,3 +6,19 @@ import Class from 'hilojs/core/Class';
  * @see {@link https://hiloteam.github.io/Hilo/docs/api-zh/symbols/Class.html}
  */
 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] 构造函数
+ */

src/core/EventMixin.js

@@ -2,7 +2,52 @@ import EventMixin from 'hilojs/event/EventMixin';
 
 /**
  * EventMixin是一个包含事件相关功能的mixin。可以通过 Object.assign(target, EventMixin) 来为target增加事件功能。
- * @namespace EventMixin
+ * @class EventMixin
  * @see {@link https://hiloteam.github.io/Hilo/docs/api-zh/symbols/EventMixin.html}
  */
 export default EventMixin;
+
+/**
+ * 增加一个事件监听。
+ * @name EventMixin#on
+ * @function
+ * @param {String} type 要监听的事件类型。
+ * @param {EventMixinCallback} listener 事件监听回调函数。
+ * @param {Boolean} [once] 是否是一次性监听，即回调函数响应一次后即删除，不再响应。
+ * @returns {any} 对象本身。链式调用支持。
+ */
+
+
+/**
+ * 删除一个事件监听。如果不传入任何参数，则删除所有的事件监听；如果不传入第二个参数，则删除指定类型的所有事件监听。
+ * @name EventMixin#off
+ * @function
+ * @param {String} [type] 要删除监听的事件类型。
+ * @param {EventMixinCallback} [listener] 要删除监听的回调函数。
+ * @returns {any} 对象本身。链式调用支持。
+*/
+
+/**
+ * 发送事件。当第一个参数类型为Object时，则把它作为一个整体事件对象。
+ * @name EventMixin#fire
+ * @function
+ * @param {String|EventObject} [type] 要发送的事件类型或者一个事件对象。
+ * @param {Object} [detail] 要发送的事件的具体信息，即事件随带参数。
+ * @returns {Boolean} 是否成功调度事件。
+ */
+
+/**
+ * 事件对象
+ * @interface EventObject
+ * @property {String} type 事件类型
+ * @property {any} [detail=null] 事件数据
+ */
+
+/**
+ * @callback EventMixinCallback
+ * @param {Object} [e] 事件对象
+ * @param {String} e.type 事件类型
+ * @param {Object} e.detail 事件数据
+ * @param {Object} e.target 事件触发对象
+ * @param {Date} e.timeStamp 时间戳
+ */

src/core/Mesh.js

@@ -54,7 +54,7 @@ const Mesh = Class.create(/** @lends Mesh.prototype */ {
     frustumTest: true,
     /**
      * @constructs
-     * @param {object} params 初始化参数，所有params都会复制到实例上
+     * @param {object} [params] 初始化参数，所有params都会复制到实例上
      */
     constructor(params) {
         Mesh.superclass.constructor.call(this, params);

src/core/Node.js

@@ -37,19 +37,19 @@ const Node = Class.create(/** @lends Node.prototype */ {
         /**
          * traverse callback 返回值，执行后不暂停 traverse
          * @memberOf Node
-         * @type {Enum}
+         * @type {any}
          */
         TRAVERSE_STOP_NONE,
         /**
          * traverse callback 返回值，执行后暂停子元素 traverse
          * @memberOf Node
-         * @type {Enum}
+         * @type {any}
          */
         TRAVERSE_STOP_CHILDREN,
         /**
          * traverse callback 返回值，执行后暂停所有 traverse
          * @memberOf Node
-         * @type {Enum}
+         * @type {any}
          */
         TRAVERSE_STOP_ALL
     },
@@ -69,11 +69,24 @@ const Node = Class.create(/** @lends Node.prototype */ {
      * @type {string}
      */
     name: '',
+    /**
+     * 动画
+     * @type {Animation}
+     * @default null
+     */
+    anim: null,
     /**
      * animation 查找 id
      * @type {String}
+     * @default ''
      */
     animationId: '',
+    /**
+     * 骨骼名称
+     * @type {String}
+     * @default ''
+     */
+    jointName: '',
     /**
      * 是否自动更新世界矩阵
      * @default true
@@ -139,7 +152,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
 
     /**
      * @constructs
-     * @param {object} params 初始化参数，所有params都会复制到实例上
+     * @param {object} [params] 初始化参数，所有params都会复制到实例上
      */
     constructor(params) {
         /**
@@ -383,7 +396,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     /**
      * _traverse
      * @private
-     * @param  {Function(Node)} callback
+     * @param  {NodeTraverseCallback} callback
      * @param  {Boolean}  onlyChild
      * @return {Enum}  TRAVERSE_STOP_ALL, TRAVERSE_STOP_CHILDREN, TRAVERSE_STOP_NONE
      */
@@ -407,7 +420,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 遍历当前元素的子孙元素
-     * @param {Function(Node)} callback 每个元素都会调用这个函数处理
+     * @param {NodeTraverseCallback} callback 每个元素都会调用这个函数处理
      * @param {Boolean} [onlyChild=false] 是否只遍历子元素
      * @return {Node} this
      */
@@ -417,7 +430,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 遍历当前元素的子孙元素(广度优先)
-     * @param {Function(Node)} callback 每个元素都会调用这个函数处理
+     * @param {NodeTraverseCallback} callback 每个元素都会调用这个函数处理
      * @param {Boolean} [onlyChild=false] 是否只遍历子元素
      * @return {Node} this
      */
@@ -447,7 +460,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 根据函数来获取一个子孙元素(广度优先)
-     * @param {Function} fn 判读函数
+     * @param {NodeGetChildByCallback} fn 判读函数
      * @return {Node|null} 返回获取到的子孙元素
      */
     getChildByFnBFS(fn) {
@@ -500,7 +513,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 根据函数来获取一个子孙元素
-     * @param {Function} fn 判读函数
+     * @param {NodeGetChildByCallback} fn 判读函数
      * @return {Node|null} 返回获取到的子孙元素
      */
     getChildByFn(fn) {
@@ -517,7 +530,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 根据函数来获取匹配的所有子孙元素
-     * @param {Function} fn 判读函数
+     * @param {NodeGetChildByCallback} fn 判读函数
      * @return {Node[]} 返回获取到的子孙元素
      */
     getChildrenByFn(fn) {
@@ -976,7 +989,7 @@ const Node = Class.create(/** @lends Node.prototype */ {
     },
     /**
      * 销毁 Node 资源
-     * @param {WebGLRenderer} renderer
+     * @param {WebGLRenderer} [renderer] stage时可以不传
      * @param {Boolean} [destroyTextures=false] 是否销毁材质的贴图，默认不销毁
      * @return {Node} this
      */
@@ -1045,3 +1058,18 @@ export default Node;
  * @property {Mesh} mesh 碰撞的 mesh
  * @property {Vector3} point 碰撞得点
  */
+
+
+/**
+ * Node traverse 回调
+ * @callback NodeTraverseCallback
+ * @param {Node} node
+ * @return {any} Node.TRAVERSE_STOP_NONE | Node.TRAVERSE_STOP_CHILDREN | Node.TRAVERSE_STOP_ALL
+ */
+
+/**
+ * Node getChildByCallback 回调
+ * @callback NodeGetChildByCallback
+ * @param {Node} node
+ * @return {boolean}
+ */

src/core/SkinedMesh.js

@@ -50,7 +50,7 @@ const SkinedMesh = Class.create(/** @lends SkinedMesh.prototype */{
     skeleton: null,
     /**
      * @constructs
-     * @param {object} params 初始化参数，所有params都会复制到实例上
+     * @param {object} [params] 初始化参数，所有params都会复制到实例上
      */
     constructor(params) {
         SkinedMesh.superclass.constructor.call(this, params);