Improvements to Can-Define Documentation (#387)

* Greatly improved propDefinition examples.

* incremental improvements to propDefinition.md

* incremental updates, es6 and spacing syntax -- mostly.

* Added more verbose examples to docs/define.md

* Updeeated examples on default.md.

* updated minor spacing and codepen examples.

* mostly fixed value.md

* fixed all codepen on valuee.md.

* fixed spelling

* improvements to serailize and identity codepens.

* Greatly improved codepen examples for type.md.

* removed working with  section as it was legacy. This was based on a pseudo-vote from Kevin and Justin.

* finished type.documentation

* greatly improved type and TypeConstructor examples and documentation.

* minor improvements.

* fixed spacing in defaultConstructor.md

* Improved an example on propDefinition.md

* changed example 'hobbies' to more applicable affectations.

* updated Getter example.

* added comments in example.

* greatly improved examples.

* removed  in favor of directly assigning.

* updated example to show relation to original constructor.

* fixed tabbing in serialize.md

Author: indifferentghost

Diff for: docs/TypeConstructor.md

@@ -6,75 +6,99 @@ value.
 
 @signature `Type`
 
-A constructor function can be provided that is called to convert incoming values set on this property, like:
+  A constructor function can be provided that is called to convert incoming values set on this property, like:
 
-```js
-{
-	prop: {
-		Type: Person
-	}
-}
-```    
+  ```js
+  import {DefineMap} from "can";
+  import {Person} from "//unpkg.com/can-demo-models@5";
 
-The `Type` constructor is called before the [can-define.types.type] property and before [can-define.types.set]. It checks if the incoming value
-is an [instanceof](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) `Type`. If it is, or if it is `null` or `undefined`, it passes the original value through.  If not, it passes the original value to `new Type(originalValue)` and returns the
-new instance to be set.
+  const Example = DefineMap.extend({
+    prop: {
+      Type: Person
+    }
+  });
+  const ex = new Example();
+  ex.prop = {first: "Justin", last: "Meyer"};
 
-@signature `{propDefinition}`
+  console.log( ex.prop instanceof Person ); //-> true
+  console.log( ex.prop.fullName ); //-> "Justin Meyer"
+  ```
+  @codepen
 
-A [can-define.types.propDefinition] that defines an inline [can-define/map/map] type.  For example:
+  The `Type` constructor is called before the [can-define.types.type] property and before [can-define.types.set]. It checks if the incoming value
+  is an [instanceof](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) `Type`. If it is, or if it is `null` or `undefined`, it passes the original value through.  If not, it passes the original value to `new Type(originalValue)` and returns the
+  new instance to be set.
 
-```js
-{
-	address: {
-		Type: {
-			street: "string",
-			city: "string"
-		}
-	}
-}
-```
+@signature `{propDefinition}`
 
-@signature `[Type|propDefinition]`
+  A [can-define.types.propDefinition] that defines an inline [can-define/map/map] type.  For example:
 
-Defines an inline [can-define/list/list] type that's an array of `Type` or inline [can-define.types.propDefinition] [can-define/map/map]
-instances.  For example:
+  ```js
+  {
+    address: {
+      Type: {
+        street: "string",
+        city: "string"
+      }
+    }
+  }
+  ```
 
-```js
-{
-	people: {
-		Type: [ Person ]
-	},
-	addresses: {
-		Type: [ {
-			street: "string",
-			city: "string"
-		} ]
-	}
-}
-```
+@signature `[Type|propDefinition]`
 
+  Defines an inline [can-define/list/list] type that's an array of `Type` or inline [can-define.types.propDefinition] [can-define/map/map]
+  instances.  For example:
+
+  ```js
+  import {DefineMap} from "can";
+
+  const List = DefineMap.extend({
+    people: {
+      Type: [ Person ]
+    },
+    addresses: {
+      Type: [ {
+        street: "string",
+        city: "string"
+      } ]
+    }
+  });
+
+  const myList = new List({
+    people: [ {first: "Justin", last: "Meyer"} ],
+    addresses: [ {street: "11 Example Ave.", city: "Chicago"} ]
+  });
+
+  console.log( myList.serialize() );
+  ```
+  @codepen
 
 @body
 
 ## Use
 
 ```js
-import { DefineMap } from "can";
+import {DefineMap, Reflect as canReflect} from "can";
 
 const Address = DefineMap.extend( {
-	street: "string",
-	city: "string"
+    street: "string",
+    city: {type:"string", default: "Chicago"}
 } );
 
 const Direction = DefineMap.extend( {
-	from: { Type: Address },
-	to: Address
+    from: { Type: Address },
+    to: Address
 } );
 
 const direction = new Direction( {
-	from: { street: "2060 N. Stave", city: "Chicago" },
-	to: new Address( { street: "123 Greenview", city: "Libertyville" } )
+    from: {street: "2060 N. Stave"},
+    to: new Address( {street: "123 Greenview", city: "Libertyville"} )
 } );
+
+console.log( direction.from instanceof Address ); //-> true
+console.log( direction.serialize() ); //-> {
+//   from: {city: "Chicago", street: "2060 N. Stave"}
+//   to: {city: "Libertyville", street: "123 Greenview"}
+// }
 ```
-@codepen
+@codepen

Diff for: docs/default.md

@@ -6,36 +6,48 @@ is read for the first time.
 
 @signature `default()`
 
-A function can be provided that returns the default value used for this property, like:
+  A function can be provided that returns the default value used for this property, like:
 
-```js
-{
-	prop: {
-		default: function() {
-			return [];
-		}
-	}
-}
-```
+  ```js
+  import {DefineMap} from "can";
 
+  const Example = DefineMap.extend( {
+    prop: {
+      default: function() {
+        return [];
+      }
+    }
+  } );
 
-If the default value should be an object of some type, it should be specified as the return value of a function (the above call signature) so that all instances of this map don't point to the same object.  For example, if the property `value` above had not returned an empty array but instead just specified an array using the next call signature below, all instances of that map would point to the same array (because JavaScript passes objects by reference).
+  const ex = new Example();
+  console.log( ex.prop.serialize() ); //-> []
+  ```
+  @codepen
 
-@return {*} The default value.  This will be passed through setter and type.
+  If the default value should be an object of some type, it should be specified as the return value of a function (the above call signature) so that all instances of this map don't point to the same object.  For example, if the property `value` above had not returned an empty array but instead just specified an array using the next call signature below, all instances of that map would point to the same array (because JavaScript passes objects by reference).
+
+  @return {*} The default value.  This will be passed through setter and type.
 
 @signature `default`
 
-Any value can be provided as the default value used for this property, like:
+  Any value can be provided as the default value used for this property, like:
 
-```js
-{
-	prop: {
-		default: 'foo'
-	}
-}
-```
+  ```js
+  import {DefineMap} from "can"
+
+  const Example = DefineMap.extend( {
+    prop: {
+      default: "foo"
+    }
+  } );
+
+  const ex = new Example();
+  console.log( ex.prop ); //-> "foo"
 
-@param {*} defaultVal The default value, which will be passed through setter and type.
+  ```
+  @codepen
+
+  @param {*} defaultVal The default value, which will be passed through setter and type.
 
 @body
 
@@ -44,24 +56,28 @@ Any value can be provided as the default value used for this property, like:
 The following defaults `age` to `0` and `address` to an object:
 
 ```js
-import { DefineMap } from "can"
-// A default age of `0`:
+import {DefineMap} from "can";
+
+
 const Person = DefineMap.extend( {
+  // A default age of `0`:
 	age: {
 		default: 0
 	},
+  // A default address:
 	address: {
-		default: function() {
+		default() {
 			return { city: "Chicago", state: "IL" };
 		}
 	}
 } );
 
 const person = new Person();
-console.log(person.age); //-> 0
+console.log( person.age ); //-> 0
+console.log( person.address.serialize() ); //-> { city: "Chicago", state: "IL" }
 ```
 @codepen
 
 ## Alternates
 
-There is a third way to provide a default value, which is explained in the [can-define.types.defaultConstructor] docs page. `default` lowercased is for providing default values for a property type, while `Default` uppercased is for providing a constructor function, which will be invoked with `new` to create a default value for each instance of this map.
+There is a third way to provide a default value, which is explained in the [can-define.types.defaultConstructor] docs page. `default`, lowercase, is for providing default values for a property type, while `[can-define.types.defaultConstructor Default]`, uppercase, is for providing a constructor function, which will be invoked with `new` to create a default value for each instance of this map.

Diff for: docs/defaultConstructor.md

@@ -5,29 +5,29 @@ Provides a constructor function to be used to provide a default value for a prop
 
 @signature `Default`
 
-A constructor function can be provided that is called to create a default value used for this property.
-This constructor will be invoked with `new` for each created instance. The default
-value is created on demand when the property is read for the first time.
-
-Specify `Default` like:
-
-```js
-{
-	prop: {
-		Default: Array
-	},
-	person: {
-		Default: Person
-	}
-}
-```
+  A constructor function can be provided that is called to create a default value used for this property.
+  This constructor will be invoked with `new` for each created instance. The default
+  value is created on demand when the property is read for the first time.
+
+  Specify `Default` like:
+
+  ```js
+  {
+    prop: {
+      Default: Array
+    },
+    person: {
+      Default: Person
+    }
+  }
+  ```
 
 @body
 
 ## Use
 
 ```js
-import { DefineMap } from "can";
+import {DefineMap} from "can";
 
 const Address = DefineMap.extend( {
 	street: { type: "string", value: "321 Longbow" },
@@ -43,7 +43,7 @@ const direction = new Direction( {
 	to: { street: "2070 N. Stave" }
 } );
 
-console.log(direction.from.street); //-> "321 Longbow"
-console.log(direction.to.street);   //-> "2070 N. Stave"
+console.log( direction.from.street ); //-> "321 Longbow"
+console.log( direction.to.street );   //-> "2070 N. Stave"
 ```
 @codepen

Diff for: docs/define.md

@@ -35,39 +35,35 @@ and [can-define/list/list] are documented here.
   	message: { type: "string" }
   } );
 
-  var greeting = new Greeting("Hello");
+  const greeting = new Greeting("Hello");
 
   canReflect.onKeyValue(greeting, "message", (newValue) => {
-	  console.log(newValue); // logs "goodbye"
+  	console.log( newValue.target.message ); //-> logs "goodbye"
   });
 
   greeting.message = "goodbye";
   ```
   @codepen
 
-@param {Object} prototype The prototype object of a constructor function or [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class). The prototype
-object will have getter/setters defined on it that carry out the defined behavior.  The prototype will also contain
-all of [can-event-queue/map/map]'s methods.
+  @param {Object} prototype The prototype object of a constructor function or [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class). The prototype object will have getter/setters defined on it that carry out the defined behavior.  The prototype will also contain all of [can-event-queue/map/map]'s methods.
 
-@param {Object<String,can-define.types.propDefinition>} propDefinitions An object of
-properties and their definitions. For example, a property (`propertyName`) has a [can-define.types.propDefinition] object with zero or more of the following behaviors:
+  @param {Object<String,can-define.types.propDefinition>} propDefinitions An object of properties and their definitions. For example, a property (`propertyName`) has a [can-define.types.propDefinition] object with zero or more of the following behaviors:
 
-```js
-define(Type.prototype, {
+  ```js
+  define(Type.prototype, {
     propertyName: {
-        default: function() { /* ... */ },
-        Default: Constructor,
-        type: function() { /* ... */ },
-        Type: Constructor,
-        get: function() { /* ... */ },
-        value: function() { /* ... */ },
-        set: function() { /* ... */ },
-        serialize: function() { /* ... */ },
-        identity: Boolean
+      default: function() { /* ... */ },
+      Default: Constructor,
+      type: function() { /* ... */ },
+      Type: Constructor,
+      get: function() { /* ... */ },
+      value: function() { /* ... */ },
+      set: function() { /* ... */ },
+      serialize: function() { /* ... */ },
+      identity: Boolean
     }
-})
-```
-
+  })
+  ```
 
 @body
 
@@ -80,8 +76,7 @@ more assumptions on the type constructor.  `can-define` can be used
 to create completely customized types.
 
 
-The following creates a
-`Person` constructor function that
+The following creates a `Person` constructor function that
 will be used to create `Person` instances with observable properties:
 
 ```js
@@ -105,13 +100,13 @@ define( Person.prototype, {
 // Create an instance
 const person = new Person( "Justin", "Meyer" );
 
-console.log( person.first )    //-> "Justin"
-console.log( person.last )     //-> "Meyer"
-console.log( person.fullName ) //-> "Justin Meyer"
+console.log( person.first ); //-> "Justin"
+console.log( person.last ); //-> "Meyer"
+console.log( person.fullName ); //-> "Justin Meyer"
 
 person.on( "fullName", function( ev, newVal, oldVal ) {
-	console.log( newVal ) //-> "Ramiya Meyer"
-	console.log( oldVal ) //-> "Justin Meyer"
+	console.log( newVal ); //-> "Ramiya Meyer"
+	console.log( oldVal ); //-> "Justin Meyer"
 } );
 
 person.first = "Ramiya";