Merge pull request #977 from bitovi/scope-docs

Scope docs

component/scope.md

@@ -8,7 +8,7 @@ instance is initialized with values specified by the component element's attribu
 @deprecated {2.1} In 2.1, [can.stache] and [can.mustache] pass values to the 
 scope differently. To pass data from the scope, you must wrap your attribute 
 value with `{}`. In 3.0, [can.mustache]
-will use [can.stache]'s method.
+will use [can.stache]'s syntax.
 
 @option {Object} A plain JavaScript object that is used to define the prototype methods and properties of 
 [can.Construct constructor function] that extends can.Map. For example:
@@ -25,7 +25,7 @@ will use [can.stache]'s method.
     })
 
 Prototype properties that have values of `"@"` are not looked up in the current scope, instead
-the literal string value of the relevant attribute is used.  For example:
+the literal string value of the relevant attribute is used (like pass by value instead of pass by reference).  For example:
 
     can.Component.extend({
       tag: "my-tag",
@@ -174,10 +174,32 @@ render the component's template, and inserted into the element:
 
 ## Values passed from attributes
 
-By default, custom tag attributes other than "class" and "id" are looked up
-in the parent scope and set as observable values on the [can.Map] instance.
+Values can be "passed" into the scope of a component, similar to passing arguments into a function. By default, 
+custom tag attributes (other than "class" and "id") are looked up
+in the parent scope and set as observable values on the [can.Map] instance. 
 
-For example, the following component requires an offset and 
+Values passed in this way are passed similar to function arguments that are "pass by reference" because they are crossbound to 
+the property in the parent scope. Changes in the parent scope property that is passed in trigger changes in this component's scope 
+property, and likewise, changes in the component's scope property trigger a change in the parent scope property.
+
+As mentioned in the deprecation warning above, using can.stache, values are passed into components like this:
+
+    <my-paginate offset='{index}' limit='{size}'></my-paginate>
+
+But using can.mustache, values are passed like this:
+
+    my-paginate offset='index' limit='size'></my-paginate>
+
+The rest of the examples in this section show can.mustache syntax (which will change to match can.stach in 3.0). 
+
+Note that using double brackets would instead render the string version of the value, and pass by value rather than by reference:
+
+    <my-paginate offset='{{index}}' limit='{{size}}'></my-paginate>
+
+The above would create an offset and limit property on the component that are initialized to whatever index and size are, NOT cross-bind 
+the offset and limit properties to the index and size.
+
+The following component requires an offset and 
 limit:
 
     can.Component.extend({
@@ -214,8 +236,19 @@ will update to:
 
 ### Using attribute values
 
-If you want the literal string value of the attribute instead of the attribute's value looked up in
-the parent scope, you can set scope properties to have values of "@".  For example:
+You can also pass a literal string value of the attribute instead of the attribute's value looked up in
+the parent scope (similar to pass by value). 
+
+To do this in can.stache, simply pass any value not wrapped in single brackets, and the scope property will 
+be initialized to this string value:
+
+    <my-tag title="hello"></my-tag>
+
+The above will create a title property in the component's scope, which has a string "hello".  If instead hello was wrapped with 
+brackets like "{hello}", a hello property would be looked up in the parent's scope.
+
+To do this in can.mustache, pass a value like in can.stache, and set the corresponding scope property in the component 
+to a value of "@".  For example:
 
     can.Component.extend({
       tag: "my-tag",
@@ -233,6 +266,8 @@ Results in:
 
     <my-tag><h1>hello</h1></my-tag>
 
+can.mustache syntax (requiring the "@") will change to can.stache in 3.0 (not requiring the "@").
+
 If the tag's `title` attribute is changed, it updates the scope property 
 automatically.  This can be seen in the following example: