documentation improvements, removing old templates

can.md

@@ -6,7 +6,36 @@
 This is the detailed documentation of the API for CanJS, a framework for building
 web applications that provides a lightweight inheritance system, observable
 objects and values, and a powerful MVC core with live-bound templates, among other
-resources. You can use it out of the box on top of jQuery, Zepto, YUI, and Mootools,
+resources. 
+
+If you are just starting with CanJS, you may want to try our [getting started guide](../guides/Tutorial.html).
+
+CanJS is composed of modules on the left. The following are typically distributed as part of the core
+framework:
+
+ - [can.Construct] - inheritable constructor functions
+ - [can.Control] - declarative event bindings
+ - [can.Observe], [can.Observe.List], [can.compute] - observable objects, list, and values.
+ - [can.Model] -  observes connected to a RESTful JSON interface
+ - [can.view] - template loading, caching, rendering
+ - [can.EJS] - live binding templates
+ - [can.route] -  back button and bookmarking support
+
+The following modules are typically distributed as plugins:
+
+ - [can.Mustache] - Live binding Handlebars and Mustache templates
+ - [can.Construct.proxy] - Proxy construct methods
+ - [can.Construct.super] - Call super methods
+ - [can.Observe.delegate] - Listen to Observe attributes
+ - [can.Observe.setter] - Use setter methods on Observes
+ - [can.Observe.attributes] - Define Observe attributes
+ - [can.Observe.validations] - Validate attributes
+ - [can.Observe.backup] - Backup and restore an Observe's state
+ - [can.Control.plugin] - Registers a jQuery plugin function for Controls[1]
+ - [View modifiers] - Use jQuery modifiers to render views[1]
+
+
+You can use it out of the box on top of jQuery, Zepto, YUI, and Mootools,
 and it's only 13K.
 
-If you are just starting with CanJS, you may want to try our [getting started guide](../guides/Tutorial.html).
+@api canjs

construct/construct.js

@@ -24,11 +24,36 @@ steal("can/util/string", function(can) {
 	 * @static
 	 */
 	can.extend(can.Construct, {
+		/**
+		 * @property {Boolean} can.Construct.constructorExtends constructorExtends
+		 * @parent can.Construct.static
+		 * 
+		 * @description
+		 * 
+		 * Toggles the behavior of a constructor function called
+		 * without `new` to extend the constructor function or
+		 * create a new instance.
+		 * 
+		 * @body
+		 * 
+		 * If `constructorExtends` is:
+		 * 
+		 *  - `true` - the constructor extends
+		 *  - `false` - a new instance of the constructor is created
+		 * 
+		 * For 1.1, `constructorExtends` defaults to true. For
+		 * 1.2, `constructorExtends` will default to false.
+		 */
+		constructorExtends: true,
 		/**
 		 * @function can.Construct.newInstance newInstance
 		 * @parent can.Construct.static
-		 * @description Create a new instance of a Construct.
-		 * @signature `newInstance([...args])`
+		 * 
+		 * @description Returns an instance of `can.Construct`. This method
+		 * can be overridden to return a cached instance.
+		 * 
+		 * @signature `can.Construct.newInstance([...args])`
+		 * 
 		 * @param {*} [args] arguments that get passed to [can.Construct::setup] and [can.Construct::init]. Note
 		 * that if [can.Construct::setup] returns an array, those arguments will be passed to [can.Construct::init]
 		 * instead.
@@ -95,16 +120,40 @@ steal("can/util/string", function(can) {
 		/**
 		 * @function can.Construct.setup setup
 		 * @parent can.Construct.static
+		 * 
 		 * @description Perform initialization logic for a constructor function.
-		 * @signature `setup(base, fullName, staticProps, protoProps)`
+		 * 
+		 * @signature `can.Construct.setup(base, fullName, staticProps, protoProps)`
+		 * 
+		 * A static `setup` method provides inheritable setup functionality
+		 * for a Constructor function. The following example
+		 * creates a Group constructor function.  Any constructor
+		 * functions that inherit from Group will be added to 
+		 * `Group.childGroups`.
+		 * 
+		 * 
+		 *     Group = can.Construct.extend({
+		 *       setup: function(Construct, fullName, staticProps, protoProps){
+		 *         this.childGroups = [];
+		 *         if(Construct !== can.Construct){
+		 *           this.childGroups(Construct)
+		 *         }
+		 *         Construct.setup.apply(this, arguments)
+		 *       }   
+		 *     },{})
+		 *     var Flock = Group.extend(...)
+		 *     Group.childGroups[0] //-> Flock
+		 * 
 		 * @param {constructor} base The base constructor that is being inherited from.
 		 * @param {String} fullName The name of the new constructor.
 		 * @param {Object} staticProps The static properties of the new constructor.
 		 * @param {Object} protoProps The prototype properties of the new constructor.
 		 *
 		 * @body
-		 * The static `setup` method is called immediately after a constructor function is created and 
-		 * set to inherit from its base constructor. It is useful for setting up additional inheritance work.
+		 * The static `setup` method is called immediately after a constructor 
+		 * function is created and 
+		 * set to inherit from its base constructor. It is useful for setting up 
+		 * additional inheritance work.
 		 * Do not confuse this with the prototype `[can.Construct::setup]` method.
 		 * 
 		 * ## Setup Extends Defaults
@@ -169,32 +218,68 @@ steal("can/util/string", function(can) {
 		},
 		// Extends classes.
 		/**
-		 * @hide
-		 * Extends a class with new static and prototype functions.  There are a variety of ways
-		 * to use extend:
-		 * 
-		 *     // with className, static and prototype functions
-		 *     can.Construct('Task',{ STATIC },{ PROTOTYPE })
-		 *     // with just classname and prototype functions
-		 *     can.Construct('Task',{ PROTOTYPE })
-		 *     // with just a className
-		 *     can.Construct('Task')
-		 * 
-		 * You no longer have to use `extend`.  Instead, you can pass those options directly to
-		 * can.Construct (and any inheriting classes):
-		 * 
-		 *     // with className, static and prototype functions
-		 *     can.Construct('Task',{ STATIC },{ PROTOTYPE })
-		 *     // with just classname and prototype functions
-		 *     can.Construct('Task',{ PROTOTYPE })
-		 *     // with just a className
-		 *     can.Construct('Task')
-		 * 
-		 * @param {String} [fullName]  the class's name (used for classes w/ introspection)
-		 * @param {Object.<string, function>} [klass]  the new class's static functions
-		 * @param {Object.<string, function>} [proto]  the new class's prototype functions
-		 * 
-		 * @return {can.Construct} returns the new class
+		 * @function can.Construct.extend extend
+		 * @parent can.Construct.static
+		 * 
+		 * @signature `can.Construct.extend([name, [staticProperties,]] instanceProperties)`
+		 * 
+		 * Extends `can.Construct`, or constructor functions derived from `can.Construct`, 
+		 * to create a new constructor function. Example:
+		 * 
+		 *     Animal = can.Construct.extend({
+		 *       sayHi: function(){
+		 *         console.log("hi")
+		 *       }
+		 *     })
+		 *     var animal = new Animal()
+		 *     animal.sayHi();
+		 * 
+		 * @param {String} [name] Creates the necessary properties and 
+		 * objects that point from the `window` to the created constructor function. The following:
+		 * 
+		 *     can.Construct.extend("company.project.Constructor",{})
+		 *     
+		 * creates a `company` object on window if it does not find one, a 
+		 * `project` object on `company` if it does not find one, and it will set the
+		 * `Constructor` property on the `project` object to point to the constructor function.
+		 * 
+		 * Finally, it sets "company.project.Constructor" as [can.Construct.fullName fullName]
+		 * and "Constructor" as [can.Construct.shortName shortName].
+		 * 
+		 * @param {Object} [staticProperties] Properties that are added the constructor 
+		 * function directly. For example:
+		 * 
+		 *     Animal = can.Construct.extend({
+		 *       findAll: function(){
+		 *         return can.ajax({url: "/animals"})
+		 *       }
+		 *     },{});
+		 *     
+		 *     Animal.findAll().then(function(json){ ... })
+		 * 
+		 * The [can.Construct.setup static setup] method can be used to 
+		 * specify inheritable behavior when a Constructor function is created.
+		 * 
+		 * @param {Object} instanceProperties Properties that belong to 
+		 * instances made with the constructor. These properties are added to the
+		 * constructor's `prototype` object. Example:
+		 * 
+		 *     Animal = can.Construct.extend({
+		 *       init: function(name){
+		 *         this.name = name;
+		 *       },
+		 *       sayHi: function(){
+		 *         console.log(this.name,"says hi")
+		 *       }
+		 *     })
+		 *     var animal = new Animal()
+		 *     animal.sayHi();
+		 * 
+		 * The [can.Construct::init init] and [can.Construct::setup setup] properties
+		 * are used for initialization.
+		 * 
+		 * @return {function} The constructor function.
+		 * 
 		 */
 		extend: function( fullName, klass, proto ) {
 			// Figure out what was passed and normalize it.
@@ -225,11 +310,11 @@ steal("can/util/string", function(can) {
 			function Constructor() {
 				// All construction is actually done in the init method.
 				if ( ! initializing ) {
-					return this.constructor !== Constructor && arguments.length ?
+					return this.constructor !== Constructor && arguments.length && Constructor.constructorExtends?
 						// We are being called without `new` or we are extending.
 						arguments.callee.extend.apply(arguments.callee, arguments) :
 						// We are being called with `new`.
-						this.constructor.newInstance.apply(this.constructor, arguments);
+						Constructor.newInstance.apply(Constructor, arguments);
 				}
 			}
 
@@ -370,7 +455,7 @@ steal("can/util/string", function(can) {
 	 * @function can.Construct.prototype.setup setup
 	 * @parent can.Construct.prototype
 	 * 
-	 * @signature `setup(...args)`
+	 * @signature `construct.setup(...args)`
 	 * 
 	 * A setup function for the instantiation of a constructor function.
 	 * 
@@ -420,7 +505,7 @@ steal("can/util/string", function(can) {
 	 *         setup: function(domElement, rawOptions) {
 	 *             // set up this.element
 	 *             this.element = $(domElement);
-	 *     
+	 *         
 	 *             // set up this.options
 	 *             this.options = can.extend({},
 	 *                                   this.constructor.defaults,
@@ -437,7 +522,10 @@ steal("can/util/string", function(can) {
 	/** 
 	 * @function can.Construct.prototype.init init
 	 * @parent can.Construct.prototype
-	 * @signature `init(...args)`
+	 * 
+	 * @description Called when a new instance of a can.Construct is created.
+	 * 
+	 * @signature `construct.init(...args)`
 	 * @param {*} args the arguments passed to the constructor (or the elements of the array returned from [can.Construct::setup])
 	 * 
 	 * @body

construct/construct.md

@@ -30,8 +30,7 @@ to [can.Construct.prototype.setup setup] and [can.Construct.prototype.init init]
 
 @signature `can.Construct([name,] [staticProperties,] instanceProperties)`
 
-Calling a constructor function without `new` currently 
-creates a new extended constructor function. Example:
+Currently creates a new extended constructor function. Example:
 
     Animal = can.Construct({
       sayHi: function(){

construct/proxy/proxy.md

@@ -3,15 +3,28 @@
 @test can/construct/proxy/test.html
 @download http://donejs.com/can/dist/can.construct.proxy.js
 
-can.Construct.proxy is a plugin that helps you manage scope when creating
-callback functions by ensuring that `this` is set correctly and sensibly
-inside callbacks.
 
-@signature `proxy(callback, [...args])`
+@description Creates callback functions that have `this` set correctly.
+
+@signature `can.Construct.proxy(callback, [...args])`
+
+Creates a static callback function that has `this` set to the constructor
+function.
+
 @param {Function|String|Array.<Function|String>} callback the function or functions to proxy
 @param {...[*]} args parameters to curry into the proxied functions
 @return {Function} a function that calls `callback` with the same context as the current context
 
+@signature `construct.proxy(callback, [...args])`
+
+Creates a static callback function that has `this` set to an instance of the constructor
+function.
+
+@param {Function|String|Array.<Function|String>} callback the function or functions to proxy.
+@param {...[*]} args parameters to curry into the proxied functions
+@return {Function} a function that calls `callback` with the same context as the current context
+
+
 @body
 `can.Construct.prototype.proxy` takes a function and returns a new function that, when invoked,
 calls the given function with the same `this` as `proxy` was called with.

construct/super/super.md

@@ -7,7 +7,10 @@
 can.Construct.super is a plugin that makes it easier to call base
 functions from inside inheriting functions.
 
-@signature `_super([...args])`
+@signature `construct._super([...args])`
+
+Calls the base constructor function's method.
+
 @param {...[*]} args parameters to pass to the base function
 
 @body

control/control.md

@@ -8,6 +8,9 @@
 @group can.Control.plugins plugins
 @body
 
+
+@signature `can.Control()
+
 can.Control helps create organized, memory-leak free, rapidly performing,
 stateful controls. Use it to create UI controls like tabs, grids, and context menus,
 and organize them into higher-order business rules with