Merge pull request canjs#937 from bitovi/docs-for-define

better docs for define

map/define/define_test.js

@@ -405,7 +405,7 @@ steal("can/map/define", "can/test", function () {
 	});
 
 
-	test("serialize", function(){
+	test("serialize basics", function(){
 		var MyMap = can.Map.extend({
 			define: {
 				name: {
@@ -427,19 +427,35 @@ steal("can/map/define", "can/test", function () {
 					serialize: function(locationIds){
 						return locationIds.join(',');
 					}
+				},
+				bared: {
+					get: function(){
+						return this.attr("name")+"+bar";
+					},
+					serialize: true
+				},
+				ignored: {
+					get: function(){
+						return this.attr("name")+"+ignored";
+					}
 				}
 			}
 		});
 
-		var map = new MyMap();
+		var map = new MyMap({name: "foo"});
 		map.attr("locations", [{id: 1, name: "Chicago"}, {id: 2, name: "LA"}]);
 		equal(map.attr("locationIds").length, 2, "get locationIds");
 		equal(map.attr("locationIds")[0], 1, "get locationIds index 0");
 		equal(map.attr("locations")[0].id, 1, "get locations index 0");
+
 		var serialized = map.serialize();
 		equal(serialized.locations, undefined, "locations doesn't serialize");
 		equal(serialized.locationIds, "1,2", "locationIds serializes");
 		equal(serialized.name, undefined, "name doesn't serialize");
+
+		equal(serialized.bared, "foo+bar", "true adds computed props");
+		equal(serialized.ignored, undefined, "computed props are not serialized by default");
+
 	});
 
 });

map/define/doc/attrDefinition.md

@@ -98,6 +98,8 @@ defines a `page` getter that reads from a map's offset and limit:
 		}
       }
     }
+
+A `get` definition makes the property __computed__ which means it will not be serialized by default.
 
 @option {can.Map.prototype.define.remove} remove A function that specifies what should happen when an attribute is removed
 with [can.Map::removeAttr removeAttr]. The following removes a `modelId` when `makeId` is removed:
@@ -110,15 +112,65 @@ with [can.Map::removeAttr removeAttr]. The following removes a `modelId` when `m
       }
     }
 
-@option {can.Map.prototype.define.serialize} serialize A function that specifies what should happen when an attribute is serialized
-with [can.Map::serialize serialize]. The following causes the serialized form of the map to contain a locationIds property, which contains comma separated id values derived from the locations property:
+@option {can.Map.prototype.define.serialize|Boolean} serialize Specifies the behavior of the 
+property when [can.Map::serialize serialize] is called. 
 
-    define: {
-      locationIds: {
-        serialize: function(locationIds){
-            return locationIds.join(',');
+By default, serialize does not include computed values. Properties with a `get` definition
+are computed and therefore are not added to the result.  Non-computed properties values are
+serialized if possible and added to the result.
+
+    Paginate = can.Map.extend({
+      define: {
+        pageNum: {
+          get: function(){ return this.offset() / 20 }
+        }
+      }
+    });
+
+    p = new Paginate({offset: 40});
+    p.serialize() //-> {offset: 40}
+
+If `true` is specified, computed properties will be serialized and added to the result.
+
+    Paginate = can.Map.extend({
+      define: {
+        pageNum: { 
+          get: function(){ return this.offset() / 20 },
+          serialize: true
+        }
+      }
+    });
+
+    p = new Paginate({offset: 40});
+    p.serialize() //-> {offset: 40, pageNum: 2}
+
+
+If `false` is specified, non-computed properties will not be added to the result.
+
+    Paginate = can.Map.extend({
+      define: {
+        offset: {
+          serialize: false
+        }
+      }
+    });
+
+    p = new Paginate({offset: 40});
+    p.serialize() //-> {}
+
+If a [can.Map.prototype.define.serialize serialize function] is specified, the result
+of the function is added to the result.
+
+    Paginate = can.Map.extend({
+      define: {
+        offset: {
+          serialize: function(offset){
+            return (offset / 20)+1
           }
+        }
       }
-    }
+    });
 
-Setting serialize to false for any property means this property will not be part of the serialized object.
+    p = new Paginate({offset: 40});
+    p.serialize() //-> {offset: 3}
+

map/define/doc/serialize.md

@@ -5,20 +5,31 @@ Called when an attribute is removed.
 
 @signature `serializer( currentValue )`
 
-@return {*|false} If `false` is returned, the value is not serialized.
+@param {*} value The current value of the attribute. 
+
+@param {String} attr The name of the attribute being serialized.
+
+@return {*|undefined} If `undefined` is returned, the value is not serialized.
+
+@this {can.Map} The map instance being serialized.
 
 @body 
 
 ## Use
 
-[can.Map::serialize serialize] is useful for serializing a can.Map instance into a more JSON-friendly form.  This can be used for many reasons, including saving a can.Model instance on the server or serializing can.route's internal can.Map for display in the hash or pushstate URL.
+[can.Map::serialize serialize] is useful for serializing a can.Map instance into 
+a more JSON-friendly form.  This can be used for many reasons, including saving a 
+[can.Model] instance on the server or serializing [can.route.map]'s internal 
+can.Map for display in the hash or pushstate URL.
 
-The serialize property allows an opportunity to define how each attribute will behave when the map is serialized.  This can be useful for:
+The serialize property allows an opportunity to define how 
+each attribute will behave when the map is serialized.  This can be useful for:
 
-* serializing complex types like dates, arrays, or objects into string formats
-* causing certain properties to be ignored when serialize is called
+- serializing complex types like dates, arrays, or objects into string formats
+- causing certain properties to be ignored when serialize is called
 
-The following causes a locationIds property to be serialized into the comma separated ID values of the location property on this map:
+The following causes a locationIds property to be serialized into 
+the comma separated ID values of the location property on this map:
 
     define: {
       locationIds: {
@@ -32,13 +43,15 @@ The following causes a locationIds property to be serialized into the comma sepa
       }
     }
 
-Setting serialize to false for any property means this property will not be part of the serialized object.  For example, if the property numPages is not greater than zero, the following example won't include it in the serialized object.
+Returning `undefined` for any property means this property will not be part of the serialized 
+object.  For example, if the property numPages is not greater than zero, the following example 
+won't include it in the serialized object.
 
     define: {
       prop: {
         numPages: function( num ){
           if(num <= 0) {
-          	return false;
+          	return undefined;
           }
           return num;
         }

map/define/test.html

@@ -17,17 +17,20 @@ <h2 id="qunit-userAgent"></h2>
 <script type="text/javascript" src="//code.jquery.com/qunit/qunit-1.14.0.js"></script>
 <script type="text/javascript">
     if (typeof QUnit === 'undefined') {
-        document.write(unescape('%3Clink rel="stylesheet" type="text/css" href="../bower_components/qunit/qunit/qunit.css" /%3E'));
-        document.write(unescape('%3Cscript type="text/javascript" src="../bower_components/qunit/qunit/qunit.js" %3E%3C/script%3E'));
+        document.write(unescape('%3Clink rel="stylesheet" type="text/css" href="../../bower_components/qunit/qunit/qunit.css" /%3E'));
+        document.write(unescape('%3Cscript type="text/javascript" src="../../bower_components/qunit/qunit/qunit.js" %3E%3C/script%3E'));
     }
-
-    QUnit.config.autostart = false;
 	setTimeout(function(){
-		steal("can/map/define/define_test.js", function() {
-			can.dev.logLevel = 1;
-	        QUnit.start();
-		});
-	},100)
+		QUnit.config.autostart = false;
+		setTimeout(function(){
+			steal("can/map/define/define_test.js", function() {
+				can.dev.logLevel = 1;
+		        QUnit.start();
+			});
+		},100);
+
+	},10);
+
 
 </script>
 </body>