From b9c09bfa4eeb031bd99495171aeb9a4a47766fb9 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sun, 17 Jan 2010 18:33:31 -0500 Subject: [PATCH] doc updates -- widened the code segments for the sake of the JavaScript --- documentation/coffee/expressions_try.coffee | 2 +- documentation/coffee/while.coffee | 2 + documentation/css/docs.css | 4 +- documentation/index.html.erb | 30 ++++++++------ documentation/js/expressions_try.js | 2 +- documentation/js/while.js | 2 + index.html | 44 +++++++++++++-------- 7 files changed, 54 insertions(+), 32 deletions(-) diff --git a/documentation/coffee/expressions_try.coffee b/documentation/coffee/expressions_try.coffee index 7b635287..13fdfec2 100644 --- a/documentation/coffee/expressions_try.coffee +++ b/documentation/coffee/expressions_try.coffee @@ -2,5 +2,5 @@ alert( try nonexistent / undefined catch error - "Caught an error: " + error + "And the error is ... " + error ) \ No newline at end of file diff --git a/documentation/coffee/while.coffee b/documentation/coffee/while.coffee index 625e6ed6..0d2b3a21 100644 --- a/documentation/coffee/while.coffee +++ b/documentation/coffee/while.coffee @@ -1,7 +1,9 @@ +# Econ 101 if this.studying_economics while supply > demand then buy() while supply < demand then sell() +# Nursery Rhyme num: 6 lyrics: while num -= 1 num + " little monkeys, jumping on the bed. diff --git a/documentation/css/docs.css b/documentation/css/docs.css index 1a4361f3..b105dd83 100644 --- a/documentation/css/docs.css +++ b/documentation/css/docs.css @@ -6,7 +6,7 @@ body { font-family: Arial, Helvetica, sans-serif; } div.container { - width: 850px; + width: 950px; margin: 50px 0 50px 50px; } p { @@ -77,7 +77,7 @@ div.code { } div.code pre { float: left; - width: 410px; + width: 450px; border-left: 1px dotted #559; padding: 0 0 0 12px; margin: 0; diff --git a/documentation/index.html.erb b/documentation/index.html.erb index 145d2e09..fa561d35 100644 --- a/documentation/index.html.erb +++ b/documentation/index.html.erb @@ -250,19 +250,20 @@ coffee --print app/scripts/*.coffee > concatenation.js

You can use newlines to break up your expression into smaller pieces, - as long as CoffeeScript can tell that the line hasn't finished - (similar to how Ruby handles it). For example, - if the line ends in an operator, dot, or keyword. + as long as CoffeeScript can determine that the line hasn't finished yet.

Functions and Invocation Functions are defined by a list of parameters, an arrow, and the function body. The empty function looks like this: =>. All - functions in CoffeeScript are named by default, for the benefit of debug messages. - If you'd like to create an anonymous function, just wrap it in parentheses. + functions in CoffeeScript are named by default, for easier debugging.

<%= code_for('functions', 'cube(5)') %> +

+ If you'd like to create an anonymous function, just wrap it in parentheses: + (x => x * x) +

Assignment @@ -272,7 +273,7 @@ coffee --print app/scripts/*.coffee > concatenation.js

<%= code_for('assignment', 'greeting') %>

- Declarations of new variables are pushed up to the top of the nearest + Declaration of new variables are pushed up to the top of the nearest lexical scope, so that assignment may always be performed within expressions.

@@ -281,7 +282,7 @@ coffee --print app/scripts/*.coffee > concatenation.js Object and Array literals look very similar to their JavaScript cousins. When you spread out each assignment on a separate line, the commas are optional. In this way, assigning object properties looks the same as - assigning local variables, and can be moved around freely. You can mix + assigning local variables, and can be moved around freely. Feel free to mix and match the two styles.

<%= code_for('objects_and_arrays', 'song.join(",")') %> @@ -306,9 +307,14 @@ coffee --print app/scripts/*.coffee > concatenation.js CoffeeScript output is wrapped in an anonymous function: (function(){ ... })(); This safety wrapper, combined with the automatic generation of the var keyword, make it exceedingly difficult - to pollute the global namespace by accident. If you'd like to create - global variables, attach them as properties on window, - or on the exports object in CommonJS. + to pollute the global namespace by accident. +

+

+ If you'd like to create top-level variables for other scripts to use, + attach them as properties on window, or on the exports + object in CommonJS. The existential operator (below), gives you a + reliable way to figure out where to add them, if you're targeting both + CommonJS and the browser: root: exports ? this

@@ -379,7 +385,7 @@ coffee --print app/scripts/*.coffee > concatenation.js The JavaScript arguments object is a useful way to work with functions that accept variable numbers of arguments. CoffeeScript provides splats ..., both for function definition as well as invocation, - making variable arguments a little bit more palatable. + making variable numbers of arguments a little bit more palatable.

<%= code_for('splats', true) %> @@ -481,7 +487,7 @@ coffee --print app/scripts/*.coffee > concatenation.js <%= code_for('expressions_try', true) %>

There are a handful of statements in JavaScript that can't be meaningfully - converted into expressions: break, continue, + converted into expressions, namely break, continue, and return. If you make use of them within a block of code, CoffeeScript won't try to perform the conversion.

diff --git a/documentation/js/expressions_try.js b/documentation/js/expressions_try.js index 7787cfb7..b0dcc446 100644 --- a/documentation/js/expressions_try.js +++ b/documentation/js/expressions_try.js @@ -3,7 +3,7 @@ try { return nonexistent / undefined; } catch (error) { - return "Caught an error: " + error; + return "And the error is ... " + error; } })()); })(); \ No newline at end of file diff --git a/documentation/js/while.js b/documentation/js/while.js index 0ac87e11..96a1626e 100644 --- a/documentation/js/while.js +++ b/documentation/js/while.js @@ -1,5 +1,6 @@ (function(){ var __a, lyrics, num; + // Econ 101 if (this.studying_economics) { while (supply > demand) { buy(); @@ -8,6 +9,7 @@ sell(); } } + // Nursery Rhyme num = 6; lyrics = (function() { __a = []; diff --git a/index.html b/index.html index f0e579af..4fe624d3 100644 --- a/index.html +++ b/index.html @@ -347,17 +347,14 @@ coffee --print app/scripts/*.coffee > concatenation.js

You can use newlines to break up your expression into smaller pieces, - as long as CoffeeScript can tell that the line hasn't finished - (similar to how Ruby handles it). For example, - if the line ends in an operator, dot, or keyword. + as long as CoffeeScript can determine that the line hasn't finished yet.

Functions and Invocation Functions are defined by a list of parameters, an arrow, and the function body. The empty function looks like this: =>. All - functions in CoffeeScript are named by default, for the benefit of debug messages. - If you'd like to create an anonymous function, just wrap it in parentheses. + functions in CoffeeScript are named by default, for easier debugging. 

square: x => x * x
 cube:   x => square(x) * x
@@ -376,6 +373,10 @@ cube = function cube(x) {
   return square(x) * x;
 };
 ;alert(cube(5));'>run: cube(5)
+

+ If you'd like to create an anonymous function, just wrap it in parentheses: + (x => x * x) +

Assignment @@ -393,7 +394,7 @@ greeting = "Hello CoffeeScript"; difficulty = 0.5; ;alert(greeting);'>run: greeting

- Declarations of new variables are pushed up to the top of the nearest + Declaration of new variables are pushed up to the top of the nearest lexical scope, so that assignment may always be performed within expressions.

@@ -402,7 +403,7 @@ difficulty = 0.5; Object and Array literals look very similar to their JavaScript cousins. When you spread out each assignment on a separate line, the commas are optional. In this way, assigning object properties looks the same as - assigning local variables, and can be moved around freely. You can mix + assigning local variables, and can be moved around freely. Feel free to mix and match the two styles. 

song: ["do", "re", "mi", "fa", "so"]
@@ -477,9 +478,14 @@ new_num = change_numbers();
       CoffeeScript output is wrapped in an anonymous function:
       (function(){ ... })(); This safety wrapper, combined with the
       automatic generation of the var keyword, make it exceedingly difficult
-      to pollute the global namespace by accident. If you'd like to create
-      global variables, attach them as properties on window,
-      or on the exports object in CommonJS.
+      to pollute the global namespace by accident. 
+    

+    
  
+      If you'd like to create top-level variables for other scripts to use, 
+      attach them as properties on window, or on the exports 
+      object in CommonJS. The existential operator (below), gives you a 
+      reliable way to figure out where to add them, if you're targeting both
+      CommonJS and the browser: root: exports ? this
     

 
     

@@ -605,7 +611,7 @@ car.speed < speed_limit ? accelerate() : arguments object is a useful way to work with
       functions that accept variable numbers of arguments. CoffeeScript provides
       splats ..., both for function definition as well as invocation,
-      making variable arguments a little bit more palatable.
+      making variable numbers of arguments a little bit more palatable.
     

     
gold: silver: the_field: "unknown"
 
@@ -694,15 +700,18 @@ backwards("stairway", "to", "heaven");
       as an expression, returning an array containing the result of each iteration
       through the loop.
     

-    
if this.studying_economics
+    
# Econ 101
+if this.studying_economics
   while supply > demand then buy()
   while supply < demand then sell()
 
+# Nursery Rhyme
 num: 6
 lyrics: while num -= 1
   num + " little monkeys, jumping on the bed.
     One fell out and bumped his head."
 
var __a, lyrics, num;
+// Econ 101
 if (this.studying_economics) {
   while (supply > demand) {
     buy();
@@ -711,6 +720,7 @@ backwards("stairway", "to", "heaven");
     sell();
   }
 }
+// Nursery Rhyme
 num = 6;
 lyrics = (function() {
   __a = [];
@@ -721,6 +731,7 @@ lyrics = (function() {
   return __a;
 })();
 


     

       There are a handful of statements in JavaScript that can't be meaningfully
-      converted into expressions: break, continue, 
+      converted into expressions, namely break, continue, 
       and return. If you make use of them within a block of code, 
       CoffeeScript won't try to perform the conversion.