[CS2] Docs updates (#4536)

* Docs: named functions and function declarations

* No more prototypal `extends`; update docs and example

* More comprehensive documentation of the existential operator; closes #1631

* Better document operators, including `from`

* No fat arrow class methods anymore

* Destructuring shouldn’t say that default values are applied in case of undefined or null

* Spinoff generator and async functions into their own sections; reorder things so that the sections on functions come just before classes, and destructuring goes next to the operators (which discuss assignment)

* Rewrite “CoffeeScript 2” section, making it less practical and more explanatory; move practical info into “Usage”

* Update “Variable Scoping and Lexical Safety” section to remove incorrect reference to Ruby (fixes #2360), add missing details about the safety wrapper, add note about `let`/`const`.

* Updated browser compiler

* Updated docs

* Rewrite Literate CoffeeScript breaking changes

* Split apart the “Breaking Changes” and “Unsupported Features” sections into separate sidebar items and files

* Add example of `not in`, closes #3281

* Fix words in bold that should be in backticks

* Consolidate some breaking changes sections

* Add Node API documentation; closes #3551

* Move the chaining documentation out of the changelog into its own section

docs/v2/test.html

@@ -860,9 +860,8 @@ <h1>CoffeeScript Test Suite</h1>
     extend = 3
     hasProp = 4
     value: 5
-    method: (bind, bind1) => [bind, bind1, extend, hasProp, @value]
-  {method} = new B
-  arrayEq [1, 2, 3, 4, 5], method 1, 2
+    method: (bind, bind1) -> [bind, bind1, extend, hasProp, @value]
+  arrayEq [1, 2, 3, 4, 5], new B().method 1, 2
 
   modulo = -1 %% 3
   eq 2, modulo
@@ -1247,42 +1246,20 @@ <h1>CoffeeScript Test Suite</h1>
   ok instance.name() is 'class'
 
 
-test "Classes with methods that are pre-bound to the instance, or statically, to the class", ->
+test "Classes with methods that are pre-bound statically, to the class", ->
 
   class Dog
     constructor: (name) ->
       @name = name
 
-    bark: =>
-      "#{@name} woofs!"
-
     @static = =>
       new this('Dog')
 
-  spark = new Dog('Spark')
-  fido  = new Dog('Fido')
-  fido.bark = spark.bark
-
-  ok fido.bark() is 'Spark woofs!'
-
   obj = func: Dog.static
 
   ok obj.func().name is 'Dog'
 
 
-test "a bound function in a bound function", ->
-
-  class Mini
-    num: 10
-    generate: =>
-      for i in [1..3]
-        =>
-          @num
-
-  m = new Mini
-  eq (func() for func in m.generate()).join(' '), '10 10 10'
-
-
 test "contructor called with varargs", ->
 
   class Connection
@@ -1587,21 +1564,6 @@ <h1>CoffeeScript Test Suite</h1>
     @B: makeFn 2
     constructor: makeFn 3
 
-test "#1182: external constructors with bound functions", ->
-  fn = ->
-    {one: 1}
-    this
-  class B
-  class A
-    constructor: fn
-    method: => this instanceof A
-  ok (new A).method.call(new B)
-
-test "#1372: bound class methods with reserved names", ->
-  class C
-    delete: =>
-  ok C::delete
-
 test "#1380: `super` with reserved names", ->
   class C
     do: -> super()
@@ -1670,7 +1632,7 @@ <h1>CoffeeScript Test Suite</h1>
     @unbound: ->
       eq this, Store
 
-    instance: =>
+    instance: ->
       ok this instanceof Store
 
   Store.bound()
@@ -1833,57 +1795,6 @@ <h1>CoffeeScript Test Suite</h1>
   ok overrideArray instanceof OverrideArray
   eq 'yes!', overrideArray.method()
 
-
-test "#2782: non-alphanumeric-named bound functions", ->
-  class A
-    'b:c': =>
-      'd'
-
-  eq (new A)['b:c'](), 'd'
-
-
-test "#2781: overriding bound functions", ->
-  class A
-    a: ->
-        @b()
-    b: =>
-        1
-
-  class B extends A
-    b: =>
-        2
-
-  b = (new A).b
-  eq b(), 1
-
-  b = (new B).b
-  eq b(), 2
-
-
-test "#2791: bound function with destructured argument", ->
-  class Foo
-    method: ({a}) => 'Bar'
-
-  eq (new Foo).method({a: 'Bar'}), 'Bar'
-
-
-test "#2796: ditto, ditto, ditto", ->
-  answer = null
-
-  outsideMethod = (func) ->
-    func.call message: 'wrong!'
-
-  class Base
-    constructor: ->
-      @message = 'right!'
-      outsideMethod @echo
-
-    echo: =>
-      answer = @message
-
-  new Base
-  eq answer, 'right!'
-
 test "#3063: Class bodies cannot contain pure statements", ->
   throws -> CoffeeScript.compile """
     class extends S
@@ -2095,9 +2006,6 @@ <h1>CoffeeScript Test Suite</h1>
       eq result.super, this
       eq result.param, @param
       eq result.method, @method
-      ok result.method isnt Test::method
-
-    method: =>
 
   nonce = {}
   new Test nonce, {}
@@ -2117,8 +2025,6 @@ <h1>CoffeeScript Test Suite</h1>
         super 'not param'
         eq @name, 'not param'
       eq @param, nonce
-      ok @method isnt Test::method
-    method: =>
   new Test true, nonce
   new Test false, nonce
 
@@ -2137,16 +2043,13 @@ <h1>CoffeeScript Test Suite</h1>
           eq (super 'param'), @;
           eq @name, 'param';
           eq @param, nonce;
-          ok @method isnt Test::method
         )
       else
         result = (
           eq (super 'not param'), @;
           eq @name, 'not param';
           eq @param, nonce;
-          ok @method isnt Test::method
         )
-    method: =>
   new Test true, nonce
   new Test false, nonce
 
@@ -2348,15 +2251,15 @@ <h1>CoffeeScript Test Suite</h1>
     make: -> "Making a #{@drink}"
 
   class B extends A
-    make: (@flavor) =>
+    make: (@flavor) ->
       super() + " with #{@flavor}"
 
   b = new B('Machiato')
   eq b.make('vanilla'),  "Making a Machiato with vanilla"
 
   # super in a bound function in a bound function
   class C extends A
-    make: (@flavor) =>
+    make: (@flavor) ->
       func = () =>
         super() + " with #{@flavor}"
       func()
@@ -9638,6 +9541,28 @@ <h1>CoffeeScript Test Suite</h1>
     };"""
   eq toJS(input), output
 
+test "export default implicit object", ->
+  input = "export default foo: 'bar', baz: 'qux'"
+  output = """
+    export default {
+      foo: 'bar',
+      baz: 'qux'
+    };"""
+  eq toJS(input), output
+
+test "export default multiline implicit object", ->
+  input = """
+    export default
+      foo: 'bar',
+      baz: 'qux'
+    """
+  output = """
+    export default {
+      foo: 'bar',
+      baz: 'qux'
+    };"""
+  eq toJS(input), output
+
 test "export default assignment expression", ->
   input = "export default foo = 'bar'"
   output = """
@@ -10855,6 +10780,18 @@ <h1>CoffeeScript Test Suite</h1>
   eq 1, obj[1]
   eq 2, obj.a
 
+test "#1263: Braceless object return", ->
+  fn = ->
+    return
+      a: 1
+      b: 2
+      c: -> 3
+
+  obj = fn()
+  eq 1, obj.a
+  eq 2, obj.b
+  eq 3, obj.c()
+
 </script>
 <script type="text/x-coffeescript" class="test" id="operators">
 # Operators
@@ -12115,16 +12052,6 @@ <h1>CoffeeScript Test Suite</h1>
       ret
   eq (new B).foo(), 10
 
-test "#2331: bound super regression", ->
-  class A
-    @value = 'A'
-    method: -> @constructor.value
-
-  class B extends A
-    method: => super()
-
-  eq (new B).method(), 'A'
-
 test "#3259: leak with @-params within destructured parameters", ->
   fn = ({@foo}, [@bar], [{@baz}]) ->
     foo = bar = baz = false

documentation/examples/breaking_change_super_in_non-class_methods_refactor_with_apply.coffee

@@ -1,4 +1,18 @@
+# Helper functions
+hasProp = {}.hasOwnProperty
+extend = (child, parent) ->
+  ctor = ->
+    @constructor = child
+    return
+  for key of parent
+    if hasProp.call(parent, key)
+      child[key] = parent[key]
+  ctor.prototype = parent.prototype
+  child.prototype = new ctor
+  child
+
+
 A = ->
 B = ->
-B extends A
+extend B, A
 B.prototype.foo = -> A::foo.apply this, arguments

documentation/examples/do.coffee

@@ -1,4 +1,5 @@
 for filename in list
   do (filename) ->
-    fs.readFile filename, (err, contents) ->
-      compile filename, contents.toString()
+    if filename not in ['.DS_Store', 'Thumbs.db', 'ehthumbs.db']
+      fs.readFile filename, (err, contents) ->
+        compile filename, contents.toString()

documentation/examples/existence_declared.coffee

@@ -0,0 +1,4 @@
+major = 'Computer Science'
+
+unless major?
+  signUpForClass 'Introduction to Wines'

documentation/examples/existence_undeclared.coffee

@@ -0,0 +1,2 @@
+if window?
+  environment = 'browser (probably)'

documentation/sections/async_functions.md

@@ -0,0 +1,9 @@
+## Async Functions
+
+ES2017’s [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are supported through the `await` keyword. Like with generators, there's no need for an `async` keyword; an async function in CoffeeScript is simply a function that awaits.
+
+Similar to how `yield return` forces a generator, `await return` may be used to force a function to be async.
+
+```
+codeFor('async', true)
+```