#713 cleanup can.Control, fixup contributing guide

contributing.md

@@ -11,9 +11,9 @@
 
 2.) Clone it with:
 
-@codestart	
-> git clone git@github.com:<your username>/canjs
-@codeend
+```
+git clone git@github.com:<your username>/canjs
+```
 
 ## Developing
 
@@ -52,16 +52,16 @@ When contributing, include tests with new features or bug fixes in a feature bra
 
 Move into the directory of your cloned repository and create a new feature branch.
 
-@codestart
-> cd canjs
-> git checkout -b html5-fix
-@codeend
+```
+cd canjs
+git checkout -b html5-fix
+```
 
 Once your happy with your changes, push to the feature branch.
 
-@codestart
-> git push origin html5-fix
-@codeend
+```
+git push origin html5-fix
+```
 
 Now you'll need to submit a Pull Request. Navigate to [Pull Requests](https://github.com/bitovi/canjs/pulls) and click the 'New Pull Request' button. Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request". The core team will be notified about your submission and let you know of any problems or targeted release date.
 
@@ -84,23 +84,29 @@ Search for previous tickets, if there is one add to that one rather than creatin
 
 ## Documentation
 
-If your pull request affects the public API, make relevant changes to the documentation. Documentation is found either inline or in markdown files in the respective directory. In order to view your changes in documentation you will need to run [CanJS.com](http://canjs.com) locally. Doing so is simple, just run the following code in the command line.
-
-@codestart
-> git clone git@github.com:bitovi/canjs.com.git
-> cd canjs.com
-> git submodule update --init --recursive
-> npm install
-> grunt
-@codeend
+If your pull request affects the public API, make relevant changes to the documentation.
+Documentation is found either inline or in markdown files in the respective directory.
+In order to view your changes in documentation you will need to run [CanJS.com](http://canjs.com) locally and regenerate the docs.
+Note that you will need to modify the `can` folder in the `canjs.com` clone to point at your local clone of CanJS. This can be
+accomplished by replacing the `can` folder in your `canjs.com` clone with a symlink, ie `mv can can.submodule && ln -s <local path to canjs> can`.
+
+```
+    git clone git@github.com:bitovi/canjs.com.git
+    cd canjs.com
+    git checkout gh-pages
+    git submodule update --init --recursive
+    npm install
+    grunt
+    ./js scripts/doc.js
+```
 
 Once the documentation is finished rendering, all the HTML files will be located in the `docs` folder. Open the documentation file you made changes to and make sure everything rendered correctly.
 
 ## Running Tests Locally
 
 Its important that all tests pass before sending a pull request. TravisCI will determine if your commits pass the tests, but while your developing you can run the QUnit tests locally. To run tests locally you need [NodeJS](http://nodejs.org/) installed and run
 
-> npm install
+npm install
 
 Then open `~/can/test/test.html` in a web browser to run all tests for all libraries.  Each module has its own tests too, you can run them by opening the `test.html` in each folder.
 
@@ -116,28 +122,22 @@ CanJS supports the following browsers:
 
 To make a build (standalone and AMD version) and run tests from the command line you will need [NodeJS](http://nodejs.com) and [Grunt](http://gruntjs.com) (`npm install grunt-cli -g`) installed. Then, in the CanJS repository folder run:
 
-@codestart
-> npm install
-@codeend
+    npm install
 
 Then you can run:
 
-@codestart
-> grunt build
-@codeend
+    grunt build
 
 It puts the downloads in `can/dist`.
 
 You can also run the tests from the command line by executing:
 
-@codestart
-> grunt test
-@codeend
+    grunt test
 
 ## Style Guide
 
 ### Linting
-Grunt provides a JSHint task to verify some basic, practical soundness of the codebase. The options are preset.
+Grunt provides a `quality` task to verify some basic, practical soundness of the codebase. The options are preset.
 
 ### Spacing
 Indentation with tabs, not spaces.
@@ -183,6 +183,7 @@ If the statement is a truthey or falsey, use implied operators.  Falseys are whe
 
 For example:
 
+```
 	// Bad
 	if(bar === false){ ... }
 
@@ -192,6 +193,7 @@ For example:
 	// Good
 	var foo = [];
 	if(!foo.length){ ... }
+```
 
 ###  Quotes
 
@@ -207,14 +209,18 @@ Strings that require inner quoting must use double outside and single inside.
 
 Single line comments go OVER the line they refer to:
 
+```
 	// We need an explicit "bar", because later in the code foo is checked.
 	var foo = "bar";
+```
 
 For long comments, use:
 
+```
 	/* myFn
 	 * Four score and seven—pause—minutes ago...
  	 */
+```
 
 ## List of heroes
 

control/control.md

@@ -65,12 +65,10 @@ lifecycle events:
 
 The following example builds up a basic todos widget for listing 
 and completing todo items. Start by creating a control constructor 
-function of your own by extending can.Control:
+function of your own by extending [can.Control] and defining an instance init method.
 
     var Todos = can.Control.extend({
-      init: function( element, options ) {
-        self.element.html('todos.ejs', new Todo.List({}) )
-      }
+      init: function( element, options ) { ... }
     });
 
 ## Creating a control instance
@@ -90,34 +88,47 @@ The control's associated [can.EJS EJS] template looks like:
 
 ### `init(element, options)`
 
-[can.Control::init] is called when a new can.Control instance is created. It is called with:
+[can.Control.prototype.init] is called with the below arguments when new instances of [can.Control] are created:
 
 - __element__ - The wrapped element passed to the 
                 control. Control accepts a
                 raw HTMLElement, a CSS selector, or a NodeList. This is
-                set as __this.element__ on the control instance.
+                set as `this.element` on the control instance.
 - __options__ - The second argument passed to new Control, extended with
                 the can.Control's static __defaults__. This is set as 
-                __this.options__ on the control instance.
+                `this.options` on the control instance. Note that static is used
+                formally to indicate that _default values are shared across control instances_.
 
-and any other arguments passed to `new can.Control()`. For example:
+Any additional arguments provided to the constructor will be passed as normal. Use [can.view] to produce a document fragment
+from your template and inject it in the passed element. Note that the `todos` parameter passed to [can.view] below
+is an instance of [can.List]:
 
     var Todos = can.Control.extend({
+
+      //defaults are merged into the options arg provided to the constructor
       defaults : { view: 'todos.ejs' }
+
     }, {
       init: function( element , options ) {
+
+        //create a pointer to the control's scope
         var self = this;
+
+        //run the Todo model's .findAll() method to produce a can.List
         Todo.findAll( {}, function( todos ) {
-    		self.element.html( self.options.view, todos );
+
+            //create a document fragment with can.view
+            //and inject it into the provided element's body
+    		self.element.html( can.view(self.options.view, todos) );
         });
       }
     });
 
-    // create a Todos with default options
+    // create a Todos Control with default options
     new Todos( document.body.firstElementChild );
 
-    // overwrite the template option
-    new Todos( $( '#todos' ), { template: 'specialTodos.ejs' } );
+    // overwrite the template default
+    new Todos( '#todos', { template: 'specialTodos.ejs' } );
 
 ### `this.element`
 
@@ -141,12 +152,7 @@ Control automatically binds prototype methods that look
 like event handlers. Listen to __click__s on `<li>` elements like:
 
     var Todos = can.Control.extend({
-      init: function( element , options ) {
-        var self = this;
-        Todo.findAll( {}, function( todos ) {
-          self.element.html( self.options.template, todos );
-        });
-      },
+      init: function( element , options ) {...},
 
       'li click': function( li, event ) {
         console.log( 'You clicked', li.text() );
@@ -168,16 +174,9 @@ To destroy a todo when its `<a href="javascript://" class="destroy">` link
 is clicked:
 
     var Todos = can.Control.extend({
-      init: function( element, options ) {
-        var self = this;
-        Todo.findAll( {}, function( todos ) {
-          self.element.html( self.options.template, todos );
-        });
-      },
+      init: function( element, options ) {...},
 
-      'li click': function( li ) {
-        li.trigger( 'selected', li.model() );
-      },
+      'li click': function( li ) {...},
 
       'li .destroy click': function( el, ev ) {
         // get the li element that has todo data
@@ -276,17 +275,9 @@ taking care of removing `<li>`s after their associated models were destroyed,
 we could implement it in `Todos` like:
 
     var Todos = can.Control.extend({
-      init: function( element, options ) {
-        var self = this;
-        Todo.findAll( {}, function( todos ) {
-          self.todosList = todos;
-          self.element.html( self.options.template, todos );
-        });
-      },
+      init: function( element, options ) {...},
 
-      'li click': function( li ) {
-        li.trigger( 'selected', li.model() );
-      },
+      'li click': function( li ) {...},
 
       'li .destroy click': function( el, ev ) {
         // get the li element that has todo data

control/control.prototype.init.md

@@ -0,0 +1,18 @@
+@function can.Control.prototype.init init
+@parent can.Control.prototype
+
+@description instance init method required for most applications of [can.Control]
+
+@signature `control.init(element,options)`
+
+@param element The wrapped element passed to the
+                control. Control accepts a
+                raw HTMLElement, a CSS selector, or a NodeList. This is
+                set as `this.element` on the control instance.
+@param options The second argument passed to new Control, extended with
+                the can.Control's static __defaults__. This is set as
+                `this.options` on the control instance. Note that static is used
+                formally to indicate that _default values are shared across control instances_.
+@body
+
+Any additional arguments provided to the constructor will be passed as normal.