// Backbone.Model

   // --------------

   // Backbone **Models** are the basic data object in the framework --

   // frequently representing a row in a table in a database on your server.

   // A discrete chunk of data and a bunch of useful, related methods for

   // performing computations and transformations on that data.

   // Create a new model with the specified attributes. A client id (`cid`)

   // is automatically generated and assigned for you.

   // Model构造器，大概在this对象上添加的属性

   // {

   //   cid : 'cxxx',

   //   attributes : {...},

   //   changed : {}

   // }

   // options可选参数（在进行model实例方法调用时还会见到更多的options参数）

   // {

   //   collection : true(false),

   //   parse : true(false),

   // }

   var Model = Backbone.Model = function(attributes, options) {

     var attrs = attributes || {};

     options || (options = {});

     // model对象唯一id

     this.cid = _.uniqueId('c');

     // model的属性集合

     this.attributes = {};

     // 指定model所属的collection

     if (options.collection) this.collection = options.collection;

     // 对attrs进行过滤，默认parse函数返回原attrs，继承时可以根据需要进行重写

     if (options.parse) attrs = this.parse(attrs, options) || {};

     // 将attrs中没有被设置的属性，设置默认值

     // 这里的defaults是自定义的，可以是{...}，也可以是返回{...}的函数

     attrs = _.defaults({}, attrs, _.result(this, 'defaults'));

     this.set(attrs, options);

     // 因为是构造函数，所以重置上述调用set操作带来的引起changed变化

     this.changed = {};

     // 执行初始化操作，用户可自定义

     this.initialize.apply(this, arguments);

   };

   // Attach all inheritable methods to the Model prototype.

   // Model实例公有方法（添加了事件机制）

   _.extend(Model.prototype, Events, {

     // A hash of attributes whose current and previous value differ.

     // 改变过的属性集合

     changed: null,

     // The value returned during the last failed validation.

     // 执行validate方法时，如果验证失败，那么失败的结果会放在该变量里

     validationError: null,

     // The default name for the JSON `id` attribute is `"id"`. MongoDB and

     // CouchDB users may want to set this to `"_id"`.

     // 自定义数据库返回的唯一键的名字

     idAttribute: 'id',

     // Initialize is an empty function by default. Override it with your own

     // initialization logic.

     // 一般会覆盖用于自定义初始化操作

     initialize: function(){},

     // Return a copy of the model's `attributes` object.

     toJSON: function(options) {

       return _.clone(this.attributes);

     },

     // Proxy `Backbone.sync` by default -- but override this if you need

     // custom syncing semantics for *this* particular model.

     // 调用Backbone.sync，可以通过改写Backbone.sync来实现自己的异步操作

     sync: function() {

       return Backbone.sync.apply(this, arguments);

     },

     // Get the value of an attribute.

     // 获取属性值

     get: function(attr) {

       return this.attributes[attr];

     },

     // Get the HTML-escaped value of an attribute.

     // 获取经过html-escaped过的属性值，主要事为了防止xss攻击

     escape: function(attr) {

       return _.escape(this.get(attr));

     },

     // Returns `true` if the attribute contains a value that is not null

     // or undefined.

     // 判断是否含有某个属性值

     has: function(attr) {

       return this.get(attr) != null;

     },

     // Set a hash of model attributes on the object, firing `"change"`. This is

     // the core primitive operation of a model, updating the data and notifying

     // anyone who needs to know about the change in state. The heart of the beast.

     // 设置属性值，触发对应属性的的change事件，触发对象的change事件

     set: function(key, val, options) {

       var attr, attrs, unset, changes, silent, changing, prev, current;

       if (key == null) return this;

       // Handle both `"key", value` and `{key: value}` -style arguments.

       // 处理属性集合，({key1: value1, key2: value2, ...}, [options])

       if (typeof key === 'object') {

         attrs = key;

         options = val;

       } else {

       // 处理(key1, value1, [options])

         (attrs = {})[key] = val;

       }

       options || (options = {});

       // Run validation.

       // 验证失败了，set也就失败了

       if (!this._validate(attrs, options)) return false;

       // Extract attributes and options.

       // unset 用于删除属性

       unset           = options.unset;

       // silent 用于控制是否触发对应属性的change事件

       silent          = options.silent;

       changes         = [];

       changing        = this._changing;

       this._changing  = true;

       // 这里判断其实是介于接下来的trigger change事件里面还可能在进行set操作

       // 而_previousAttributes和changed依附于this对象实现共享

       // 这里是考虑到用户自定义change回调时，循环迭代的问题

       if (!changing) {

         // 保存修改前的属性

         this._previousAttributes = _.clone(this.attributes);

         this.changed = {};

       }

       current = this.attributes, prev = this._previousAttributes;

       // Check for changes of `id`.

       // 设置id，这里的id是只数据库中的唯一键，不同于cid

       if (this.idAttribute in attrs) this.id = attrs[this.idAttribute];

       // For each `set` attribute, update or delete the current value.

       for (attr in attrs) {

         val = attrs[attr];

         // 与当前值就行比较，如果不一样，那么记录这个改变

         if (!_.isEqual(current[attr], val)) changes.push(attr);

         if (!_.isEqual(prev[attr], val)) {

           // 记录改变的属性

           this.changed[attr] = val;

         } else {

           // 如果在迭代中属性又还原不变了，那么删除掉

           delete this.changed[attr];

         }

         // 删除或者更新属性

         unset ? delete current[attr] : current[attr] = val;

       }

       // Trigger all relevant attribute changes.

       // 触发属性改变的事件，如：change:attr1

       if (!silent) {

         if (changes.length) this._pending = true;

         for (var i = 0, l = changes.length; i < l; i++) {

           this.trigger('change:' + changes[i], this, current[changes[i]], options);

         }

       }

       // You might be wondering why there's a `while` loop here. Changes can

       // be recursively nested within `"change"` events.

       // 这里返回this，是因为上面进行trigger change:attr1时，用户自定义函数可能会再次进行set操作

       // 而接下来的有些操作是针对对象本身的，只需要被执行一次

       if (changing) return this;

       if (!silent) {

         // 如果属性有改变，那么触发对象的change事件

         // 这里的循环同样是为了处理change事件的回调函数里面包含set操作而引发change事件

         // 因为上述的changing会进行return，那么通过this._pending来进行while判断，来执行多次对象的change事件回调

         // 这里依然是循环迭代的问题

         while (this._pending) {

           this._pending = false;

           this.trigger('change', this, options);

         }

       }

       // 恢复状态

       this._pending = false;

       this._changing = false;

       return this;

     },

     // Remove an attribute from the model, firing `"change"`. `unset` is a noop

     // if the attribute doesn't exist.

     // unset实质是利用set方法，只需将options.unset设置为true

     unset: function(attr, options) {

       return this.set(attr, void 0, _.extend({}, options, {unset: true}));

     },

     // Clear all attributes on the model, firing `"change"`.

     // 清除所有属性

     clear: function(options) {

       var attrs = {};

       for (var key in this.attributes) attrs[key] = void 0;

       return this.set(attrs, _.extend({}, options, {unset: true}));

     },

     // Determine if the model has changed since the last `"change"` event.

     // If you specify an attribute name, determine if that attribute has changed.

     hasChanged: function(attr) {

       // 如果attr为空，那么通过查看this.changed来判断对象是否改变（即是否有某一属性改变）

       if (attr == null) return !_.isEmpty(this.changed);

       // 返回是否某一个特定属性改变了

       return _.has(this.changed, attr);

     },

     // Return an object containing all the attributes that have changed, or

     // false if there are no changed attributes. Useful for determining what

     // parts of a view need to be updated and/or what attributes need to be

     // persisted to the server. Unset attributes will be set to undefined.

     // You can also pass an attributes object to diff against the model,

     // determining if there *would be* a change.

     // 返回changed属性列表，没有改变则返回false

     // 如果有传递diff，那么就进行attributes和diff的比较，筛选出属性值不一样的属性

     changedAttributes: function(diff) {

       if (!diff) return this.hasChanged() ? _.clone(this.changed) : false;

       var val, changed = false;

       // 还是考虑循环迭代的问题

       var old = this._changing ? this._previousAttributes : this.attributes;

       for (var attr in diff) {

         if (_.isEqual(old[attr], (val = diff[attr]))) continue;

         (changed || (changed = {}))[attr] = val;

       }

       return changed;

     },

     // Get the previous value of an attribute, recorded at the time the last

     // `"change"` event was fired.

     // 返回修改前的某个属性值

     previous: function(attr) {

       if (attr == null || !this._previousAttributes) return null;

       return this._previousAttributes[attr];

     },

     // Get all of the attributes of the model at the time of the previous

     // `"change"` event.

     // 返回修改前的属性集合

     previousAttributes: function() {

       return _.clone(this._previousAttributes);

     },

     // Fetch the model from the server. If the server's representation of the

     // model differs from its current attributes, they will be overridden,

     // triggering a `"change"` event.

     // 从服务器端获取数据，填充model

     fetch: function(options) {

       options = options ? _.clone(options) : {};

       if (options.parse === void 0) options.parse = true;

       var model = this;

       var success = options.success;

       // 回调success函数

       options.success = function(resp) {

         // 设置model的值（可能会验证失败），那么返回false

         if (!model.set(model.parse(resp, options), options)) return false;

         if (success) success(model, resp, options);

         model.trigger('sync', model, resp, options);

       };

       // 包装回调error函数

       wrapError(this, options);

       // 异步获取数据

       return this.sync('read', this, options);

     },

     // Set a hash of model attributes, and sync the model to the server.

     // If the server returns an attributes hash that differs, the model's

     // state will be `set` again.

     save: function(key, val, options) {

       var attrs, method, xhr, attributes = this.attributes;

       // Handle both `"key", value` and `{key: value}` -style arguments.

       // 上述所说的参数兼容

       if (key == null || typeof key === 'object') {

         attrs = key;

         options = val;

       } else {

         (attrs = {})[key] = val;

       }

       // 保存前要要做前端验证

       options = _.extend({validate: true}, options);

       // If we're not waiting and attributes exist, save acts as

       // `set(attr).save(null, opts)` with validation. Otherwise, check if

       // the model will be valid when the attributes, if any, are set.

       // options.wait为true用于等待服务器返回结果，再进行属性值的设置（进而view变化）

       // 为false的话，先进行数据验证，再设置属性值（改变view, 拥有更好的用户体验），再提交数据，

       //（这样的话等待服务器返回结果先还原attributes，进行属性值的set操作，包含验证）

       if (attrs && !options.wait) {

         if (!this.set(attrs, options)) return false;

       } else {

         if (!this._validate(attrs, options)) return false;

       }

       // Set temporary attributes if `{wait: true}`.

       // 因为接下来的Backbone.async中的再取数据时，会先取options.attrs的值，

       // 取不到就会执行model.toJson()来获得所有属性作为数据

       // 这里暂时改变this.attributes的值，不用set（因为set还要触发change等等）

       if (attrs && options.wait) {

         this.attributes = _.extend({}, attributes, attrs);

       }

       // After a successful server-side save, the client is (optionally)

       // updated with the server-side state.

       // 数据过滤

       if (options.parse === void 0) options.parse = true;

       var model = this;

       var success = options.success;

       options.success = function(resp) {

         // Ensure attributes are restored during synchronous saves.

         // 还原属性值

         model.attributes = attributes;

         var serverAttrs = model.parse(resp, options);

         // 用服务端的修正的数据覆盖并合并attrs

         if (options.wait) serverAttrs = _.extend(attrs || {}, serverAttrs);

         // 服务器端返回的数据更新attributes

         // 对于wait为true的情况，此时view才刚得以变化

         // 对于wait为false的情况，应该再此时再一次对view进行改变或者纠正，

         if (_.isObject(serverAttrs) && !model.set(serverAttrs, options)) {

           return false;

         }

         // 成功回调函数

         if (success) success(model, resp, options);

         model.trigger('sync', model, resp, options);

       };

       wrapError(this, options);

       // 新数据用create来创建

       // 否则用patch表示只提交改变的attrs，或者update表示提交所有的属性

       method = this.isNew() ? 'create' : (options.patch ? 'patch' : 'update');

       if (method === 'patch') options.attrs = attrs;

       xhr = this.sync(method, this, options);

       // Restore attributes.

       // 还原之前为了提交数据的临时改变

       if (attrs && options.wait) this.attributes = attributes;

       return xhr;

     },

     // Destroy this model on the server if it was already persisted.

     // Optimistically removes the model from its collection, if it has one.

     // If `wait: true` is passed, waits for the server to respond before removal.

     // 删除服务器端model数据

     destroy: function(options) {

       options = options ? _.clone(options) : {};

       var model = this;

       var success = options.success;

       var destroy = function() {

         model.trigger('destroy', model, model.collection, options);

       };

       options.success = function(resp) {

         // 等待服务器端返回或者新model，执行前端destory

         if (options.wait || model.isNew()) destroy();

         if (success) success(model, resp, options);

         // 不是新model执行远程请求成功的sync事件

         if (!model.isNew()) model.trigger('sync', model, resp, options);

       };

       // 新数据，服务器端不存在，那么只需要进行本地操作就行了

       if (this.isNew()) {

         options.success();

         return false;

       }

       wrapError(this, options);

       // 异步删除

       var xhr = this.sync('delete', this, options);

       // 不等待服务器返回结果，先前端删除

       if (!options.wait) destroy();

       return xhr;

     },

     // Default URL for the model's representation on the server -- if you're

     // using Backbone's restful methods, override this to change the endpoint

     // that will be called.

     // 返回当前model实例对应的url

     // 默认规则是：[collection.url]/[id]

     url: function() {

       var base = _.result(this, 'urlRoot') || _.result(this.collection, 'url') || urlError();

       if (this.isNew()) return base;

       return base + (base.charAt(base.length - 1) === '/' ? '' : '/') + encodeURIComponent(this.id);

     },

     // **parse** converts a response into the hash of attributes to be `set` on

     // the model. The default implementation is just to pass the response along.

     // 对数据进行解析过滤，用户可根据需求自定义

     parse: function(resp, options) {

       return resp;

     },

     // Create a new model with identical attributes to this one.

     // 克隆当前对象（即用相同attributes初始化）

     clone: function() {

       return new this.constructor(this.attributes);

     },

     // A model is new if it has never been saved to the server, and lacks an id.

     // 通过this.id来判断对象数据是否是从服务器取过来的，因为数据库的数据都是有唯一id的嘛

     isNew: function() {

       return this.id == null;

     },

     // Check if the model is currently in a valid state.

     // 检查当前的attributes是否合法，返回验证结果

     isValid: function(options) {

       return this._validate({}, _.extend(options || {}, { validate: true }));

     },

     // Run validation against the next complete set of model attributes,

     // returning `true` if all is well. Otherwise, fire an `"invalid"` event.

     // 对进行set或者save操作时，会对设置的属性数据进行验证

     _validate: function(attrs, options) {

       // 验证的条件

       // 1. options有设置validate参数为true

       // 2. 存在自定义的validate函数

       if (!options.validate || !this.validate) return true;

       // 将需要验证的attrs和对象原有的this.attributes属性合并到一个空对象上

       // 目的是，用户用validate时，可能需要参考一些已经设置好的属性值

       attrs = _.extend({}, this.attributes, attrs);

       // 验证函数验证失败返回错误信息，成功返回空值

       var error = this.validationError = this.validate(attrs, options) || null;

       if (!error) return true;

       // 验证失败，触发invalid事件

       this.trigger('invalid', this, error, _.extend(options, {validationError: error}));

       return false;

     }

   });

   // 添加几个用的underscore.js里的方法到model中，用于处理this.attributes，

   // 毕竟this.attributes是个对象也是个集合嘛，用underscore会很方便

   // Underscore methods that we want to implement on the Model.

   var modelMethods = ['keys', 'values', 'pairs', 'invert', 'pick', 'omit'];

   // Mix in each Underscore method as a proxy to `Model#attributes`.

   _.each(modelMethods, function(method) {

     Model.prototype[method] = function() {

       var args = slice.call(arguments);

       // 第一个参数时属性集合

       args.unshift(this.attributes);

       return _[method].apply(_, args);

     };

   });