Corrected jsdocs

ecomfe · Feb 27, 2013 · d2a72d6 · d2a72d6
1 parent 1d77687
commit d2a72d6
Show file tree

Hide file tree

Showing 15 changed files with 274 additions and 50 deletions.
diff --git a/src/Action.js b/src/Action.js
@@ -20,6 +20,7 @@ define(
          * 该类制定了一个完整的Action的执行周期
          *
          * @constructor
+         * @extends Observable
          */
         function Action() {
             Observable.apply(this, arguments);
@@ -29,27 +30,41 @@ define(
          * 当前Action运行上下文
          *
          * @type {Object}
+         * @protected
          */
         Action.prototype.context = null;
 
         /**
          * 指定对应的Model类型
          *
-         * @type {function|null}
+         * @type {?function}
+         * @protected
          */
         Action.prototype.modelType = null;
 
         /**
          * 指定对应的View类型
          *
-         * @type {function|null}
+         * @type {?function}
+         * @protected
          */
         Action.prototype.viewType = null;
 
         /**
          * 进入Action执行周期
+         *
+         * @param {Object} context 进入Action的上下文
+         * @param {URL} context.url 当前的URL
+         * @param {?URL} context.referrer 来源的URL
+         * @param {string} container 用来展现当前Action的DOM容器的id
+         * @public
          */
         Action.prototype.enter = function(context) {
+            /**
+             * 进入Action生命周期
+             *
+             * @event enter
+             */
             this.fire('enter');
 
             this.context = context;
@@ -68,26 +83,59 @@ define(
 
         /**
          * 创建对应的Model对象
+         *
+         * @param {Object} context 进入Action的上下文
+         * @param {URL} context.url 当前的URL
+         * @param {?URL} context.referrer 来源的URL
+         * @param {string} container 用来展现当前Action的DOM容器的id
+         * @return {Object} 当前Action需要使用的Model对象
+         * @protected
          */
         Action.prototype.createModel = function(context) {
             return this.modelType ? new this.modelType(context) : {};
         };
 
         /**
          * 加载完Model后，进入View相关的逻辑
+         *
+         * @private
          */
         Action.prototype.forwardToView = function() {
+            /**
+             * Model加载完成时触发
+             *
+             * @event modelloaded
+             */
             this.fire('modelloaded');
 
             this.view = this.createView();
             if (this.view) {
                 this.view.model = this.model;
                 this.view.container = this.context.container;
+
+                /**
+                 * 视图开始渲染时触发
+                 *
+                 * @event beforerender
+                 */
                 this.fire('beforerender');
+
                 this.view.render();
+
+                /**
+                 * 视图渲染完毕后触发
+                 *
+                 * @event rendered
+                 */
                 this.fire('rendered');
 
                 this.initBehavior();
+
+                /**
+                 * Action进入完毕后触发
+                 *
+                 * @event entercomplete
+                 */
                 this.fire('entercomplete');
             }
             else {
@@ -97,21 +145,33 @@ define(
 
         /**
          * 创建对应的View对象
+         *
+         * @return {Object} 当前Action需要使用的View对象
+         * @public
          */
         Action.prototype.createView = function() {
             return this.viewType ? new this.viewType() : null;
         };
 
         /**
          * 处理与View相关的交互逻辑
+         *
+         * @protected
          */
         Action.prototype.initBehavior = function() {
         };
 
         /**
          * 离开当前Action，清理Model和View
+         *
+         * @protected
          */
         Action.prototype.leave = function() {
+            /**
+             * 准备离开Action时触发
+             *
+             * @event beforeleave
+             */
             this.fire('beforeleave');
 
             if (this.model) {
@@ -128,6 +188,11 @@ define(
                 this.view = null;
             }
 
+            /**
+             * 离开Action后触发
+             *
+             * @event leave
+             */
             this.fire('leave');
         };
 

diff --git a/src/Deferred.js b/src/Deferred.js
@@ -100,6 +100,8 @@ define(
          * Deferred类
          * 
          * 类似于jQuery的Deferred对象，是对异步操作的一种封装
+         *
+         * @constructor
          */
         function Deferred() {
             this._state = 'pending';
@@ -120,11 +122,11 @@ define(
         }
 
         /**
-         * 判断一个对象是否是一个`Promise`
+         * 判断一个对象是否是一个`Promise`对象
          * 
          * 该方法采用灵活的判断方式，并非要求`value`为`Deferred`的实例
          *
-         * @param {Any} value 需要判断的对象
+         * @param {*} value 需要判断的对象
          * @return {boolean} 如果`value`是`Promise`对象，则返回true
          */
         Deferred.isPromise = function(value) {
@@ -134,7 +136,8 @@ define(
         /**
          * 将当前对象状态设置为**resolved**，并执行所有成功回调函数
          *
-         * @param {Any...} args 执行回调时的参数
+         * @param {...*} args 执行回调时的参数
+         * @public
          */
         Deferred.prototype.resolve = function() {
             if (this._state !== 'pending') {
@@ -150,7 +153,8 @@ define(
         /**
          * 将当前对象状态设置为**rejected**，并执行所有失败回调函数
          *
-         * @param {Any...} args 执行回调时的参数
+         * @param {...*} args 执行回调时的参数
+         * @public
          */
         Deferred.prototype.reject = function() {
             if (this._state !== 'pending') {
@@ -170,6 +174,7 @@ define(
          *
          * @param {function} callback 需要添加的回调函数
          * @return {Promise} 新的`Promise`对象
+         * @public
          */
         Deferred.prototype.done = function(callback) {
             return this.then(callback);
@@ -182,6 +187,7 @@ define(
          *
          * @param {function} callback 需要添加的回调函数
          * @return {Promise} 新的`Promise`对象
+         * @public
          */
         Deferred.prototype.fail = function(callback) {
             return this.then(null, callback);
@@ -195,6 +201,7 @@ define(
          *
          * @param {function} callback 需要添加的回调函数
          * @return {Promise} 新的`Promise`对象
+         * @public
          */
         Deferred.prototype.always = function(callback) {
             return this.then(callback, callback);
@@ -220,9 +227,10 @@ define(
          * - 如果处在**resolved**状态，则成功回调函数会被立即异步执行
          * - 如果处在**rejected**状态，则失败回调函数会被立即异步执行
          *
-         * @param {function} done 成功时执行的回调函数
+         * @param {?function} done 成功时执行的回调函数
          * @param {function=} fail 失败时执行的回调函数，可选参数
          * @return {Promise} 新的`Promise`对象
+         * @public
          */
         Deferred.prototype.then = function(done, fail) {
             var deferred = new Deferred();
@@ -239,6 +247,7 @@ define(
          * 获取当前对象的状态
          *
          * @return {string} 返回**pending**、**resolved**或**rejected**
+         * @public
          */
         Deferred.prototype.state = function() {
             return this._state;
@@ -248,6 +257,7 @@ define(
          * 判断当前对象是否处在**resolved**状态
          *
          * @return {boolean} 表示当前对象是否处在**resolved**状态
+         * @public
          */
         Deferred.prototype.isResolved = function() {
             return this._state === 'resolved';
@@ -257,6 +267,7 @@ define(
          * 判断当前对象是否处在**rejected**状态
          *
          * @return {boolean} 表示当前对象是否处在**rejected**状态
+         * @public
          */
         Deferred.prototype.isRejected = function() {
             return this._state === 'rejected';
@@ -277,6 +288,7 @@ define(
          * - `reject`
          *
          * @return {Promise} 一个Promise对象
+         * @public
          */
         Deferred.prototype.promise = function() {
             return this._promise;
@@ -300,9 +312,10 @@ define(
          * - 如果给定参数只有一个，使用这一个参数
          * - 如果给定多个参数，则提供一个数组包含这些参数
          * 
-         * 本方法对参数的方法与`Array.prototyp.concat`相同，如果任意一个参数是数组则会展开
+         * 本方法对参数的方法与`Array.prototyp.concat`相同，
+         * 如果任意一个参数是数组则会展开
          *
-         * @param {Promise|Array.<Promise>...} 需要组合的`Promise`对象或`Promise`对象数组
+         * @param {...Promise | ...Array.<Promise>} 需要组合的`Promise`对象
          * @return {Promise} 一个新的`Promise`对象
          */
         Deferred.join = function() {
@@ -352,7 +365,7 @@ define(
         /**
          * 返回一个已经处于**resolved**状态的`Promise`对象
          *
-         * @param {Any...} 用于调用`resolve`方法的参数
+         * @param {...*} 用于调用`resolve`方法的参数
          * @return {Promise} 一个已经处于**resolved**状态的`Promise`对象
          */
         Deferred.resolved = function() {
@@ -364,7 +377,7 @@ define(
         /**
          * 返回一个已经处于**rejected**状态的`Promise`对象
          *
-         * @param {Any...} 用于调用`reject`方法的参数
+         * @param {...*} 用于调用`reject`方法的参数
          * @return {Promise} 一个已经处于**rejected**状态的`Promise`对象
          */
         Deferred.rejected = function() {

diff --git a/src/Model.js b/src/Model.js
@@ -147,6 +147,7 @@ define(
          * 该Model类为一个通用的可配置的基类，提供了数据加载的相关方法
          *
          * @constructor
+         * @extends Observable
          * @param {Object=} context 初始化的数据
          */
         function Model(context) {
@@ -249,13 +250,17 @@ define(
          * 
          * - 普通的函数，映射为`{ retrieve: {fn}, dump: true }`
          * - 对象中的一个属性，映射为`{ retrieve: {fn}, key: {key} }`
+         *
+         * @type {?Object | ?Array | ?function}
+         * @protected
          */
         Model.prototype.datasource = null;
 
         /**
          * 加载当前Model
          * 
          * @return {Promise} `Promise`对象，在数据加载且`prepare`方法执行后触发
+         * @public
          */
         Model.prototype.load = function() {
             var loading = load(this, this.datasource);
@@ -277,6 +282,10 @@ define(
          * 该方法默认不执行任何逻辑
          * 
          * 如果在`prepare`方法中有异步的操作，可以让方法返回一个`Promise`对象
+         *
+         * @return {?Promise} 如果`prepare`的逻辑中有异步操作，
+         * 则返回一个`Promise`对象，通知调用者等待
+         * @protected
          */
         Model.prototype.prepare = function() {
         };
@@ -285,7 +294,8 @@ define(
          * 获取对应键的值
          *
          * @param {string} key 键名
-         * @return {Any} `key`对应的值
+         * @return {*} `key`对应的值
+         * @public
          */
         Model.prototype.get = function(key) {
             return this._store[key];
@@ -294,8 +304,9 @@ define(
         /**
          * 设置值
          *
-         * @param {string|Object} key 键名，如果是对象，则把对象里的每个键加入
-         * @param {Any=} value 对应的值，如果`key`是对象，则没有此参数
+         * @param {string | Object} key 键名，如果是对象，则把对象里的每个键加入
+         * @param {*=} value 对应的值，如果`key`是对象，则没有此参数
+         * @public
          */
         Model.prototype.set = function(key, value) {
             if (arguments.length >= 2) {
@@ -313,7 +324,8 @@ define(
          * 删除对应键的值
          *
          * @param {string} key 键名
-         * @return {Any} 在删除前`key`对应的值
+         * @return {*} 在删除前`key`对应的值
+         * @public
          */
         Model.prototype.remove = function(key) {
             var value = this._store[key];
@@ -326,6 +338,7 @@ define(
          *
          * @param {string} key 键名
          * @return {Model} `key`对应的值组装成的新的`Model`对象
+         * @public
          */
         Model.prototype.getAsModel = function(key) {
             var value = this.get(key);
@@ -336,6 +349,8 @@ define(
          * 将当前`Model`对象展出为一个普通的对象
          *
          * @return {Object} 一个普通的对象，修改该对象不会影响到当前`Model`对象
+         * @public
+         * @override
          */
         Model.prototype.valueOf = function() {
             // 为保证`valueOf`获取对象后修改不会影响到当前`Model`对象，
@@ -348,6 +363,7 @@ define(
          * 克隆当前`Model`对象，产生一个新的`Model`对象
          *
          * @return {Model} 克隆后的新`Model`对象
+         * @public
          */
         Model.prototype.clone = function() {
             return new Model(this._store);