Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[CS2] 2.0.0-beta1 docs #4494

Merged
merged 8 commits into from
Apr 10, 2017
Merged

[CS2] 2.0.0-beta1 docs #4494

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
36a1750
Update package versions; remove marked
GeoffreyBooth Apr 9, 2017
3e6cabd
Revise docs to use Markdown-It: tables are now GitHub-Flavored Markdo…
GeoffreyBooth Apr 9, 2017
d9cceba
Add anchors for sub-sections
GeoffreyBooth Apr 9, 2017
39a3caf
Add syntax highlighting to uneducable code blocks; fix missing italic…
GeoffreyBooth Apr 9, 2017
8f4d6a3
Update docs about breaking changes in Literate CoffeeScript, move Bre…
GeoffreyBooth Apr 9, 2017
7e8dbb0
Update docs regarding destructuring default values breaking change
GeoffreyBooth Apr 9, 2017
eccae6c
Update changelog, with spitball release date for beta1
GeoffreyBooth Apr 9, 2017
f13bbb0
Fix highlight function return statement
GeoffreyBooth Apr 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions Cakefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,22 +199,36 @@ buildDocs = (watch = no) ->
codeFor = require "./documentation/v#{majorVersion}/code.coffee"

htmlFor = ->
marked = require 'marked'
markdownRenderer = new marked.Renderer()
markdownRenderer.heading = (text, level) ->
"<h#{level}>#{text}</h#{level}>" # Don’t let marked add an id
markdownRenderer.code = (code) ->
hljs = require 'highlight.js'
hljs.configure classPrefix: ''
markdownRenderer = require('markdown-it')
html: yes
typographer: yes
highlight: (str, lang) ->
# From https://github.com/markdown-it/markdown-it#syntax-highlighting
if lang and hljs.getLanguage(lang)
try
return hljs.highlight(lang, str).value
catch ex
return '' # No syntax highlighting
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line should be dedented once according to the documentation you linked to.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch! Probably didn’t matter because highlight.js never threw an exception, but can’t hurt to get it right.



# Add some custom overrides to Markdown-It’s rendering, per
# https://github.com/markdown-it/markdown-it/blob/master/docs/architecture.md#renderer
defaultFence = markdownRenderer.renderer.rules.fence
markdownRenderer.renderer.rules.fence = (tokens, idx, options, env, slf) ->
code = tokens[idx].content
if code.indexOf('codeFor(') is 0 or code.indexOf('releaseHeader(') is 0
"<%= #{code} %>"
else
"<pre><code>#{code}</code></pre>" # Default
"<blockquote class=\"uneditable-code-block\">#{defaultFence.apply @, arguments}</blockquote>"

(file, bookmark) ->
md = fs.readFileSync "#{sectionsSourceFolder}/#{file}.md", 'utf-8'
md = md.replace /<%= releaseHeader %>/g, releaseHeader
md = md.replace /<%= majorVersion %>/g, majorVersion
md = md.replace /<%= fullVersion %>/g, CoffeeScript.VERSION
html = marked md, renderer: markdownRenderer
html = markdownRenderer.render md
html = _.template(html)
codeFor: codeFor()
releaseHeader: releaseHeader
Expand Down
914 changes: 481 additions & 433 deletions docs/v2/index.html
View file
Open in desktop

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions documentation/examples/breaking_change_destructuring_default_values.coffee
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{a = 1} = {a: null}

a # Equals 1 in CoffeeScript 1.x, null in CoffeeScript 2
67 changes: 52 additions & 15 deletions documentation/sections/breaking_changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,30 @@

CoffeeScript 2 aims to output as much idiomatic ES2015+ syntax as possible with as few breaking changes from CoffeeScript 1.x as possible. Some breaking changes, unfortunately, were unavoidable.

### Function parameter default values
<section id="breaking-changes-default-values">

Per the [ES2015 spec regarding default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters), default values are only applied when a parameter value is missing or `undefined`. In CoffeeScript 1.x, the default value would be applied in those cases but also if the parameter value was `null`.
### Default values for function parameters and destructured elements

Per the [ES2015 spec regarding function default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) and [destructuring default values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Default_values), default values are only applied when a value is missing or `undefined`. In CoffeeScript 1.x, the default value would be applied in those cases but also if the value was `null`.

```
codeFor('breaking_change_function_parameter_default_values', 'f(null)')
```

```
codeFor('breaking_change_destructuring_default_values', 'a')
```

</section>
<section id="breaking-changes-bound-generator-functions">

### Bound generator functions

Bound generator functions, a.k.a. generator arrow functions, [aren’t allowed in ECMAScript](http://stackoverflow.com/questions/27661306/can-i-use-es6s-arrow-function-syntax-with-generators-arrow-notation). You can write `function*` or `=>`, but not both. Therefore, CoffeeScript code like this:

> ```coffee
f = => yield this # Throws a compiler error
```coffee
f = => yield this
# Throws a compiler error
```

Needs to be rewritten the old-fashioned way:
Expand All @@ -24,38 +34,48 @@ Needs to be rewritten the old-fashioned way:
codeFor('breaking_change_bound_generator_function')
```

</section>
<section id="breaking-changes-classes">

### Classes are compiled to ES2015 classes

ES2015 classes and their methods have some restrictions beyond those on regular functions.

Class constructors can’t be invoked without `new`:

> ```coffee
(class)() # Throws a TypeError at runtime
```coffee
(class)()
# Throws a TypeError at runtime
```

Derived (extended) class `constructor`s cannot use `this` before calling `super`:

> ```coffee
```coffee
class B extends A
constructor: -> this # Throws a compiler error
constructor: -> this
# Throws a compiler error
```

Class methods can’t be used with `new` (uncommon):

> ```coffee
```coffee
class Namespace
@Klass = ->
new Namespace.Klass # Throws a TypeError at runtime
new Namespace.Klass
# Throws a TypeError at runtime
```

</section>
<section id="breaking-changes-bare-super">

### Bare `super`

Due to a syntax clash with `super` with accessors, bare `super` no longer compiles to a super call forwarding all arguments.

> ```coffee
```coffee
class B extends A
foo: -> super # Throws a compiler error
foo: -> super
# Throws a compiler error
```

Arguments can be forwarded explicitly using splats:
Expand All @@ -70,15 +90,19 @@ Or if you know that the parent function doesn’t require arguments, just call `
codeFor('breaking_change_super_without_arguments')
```

</section>
<section id="breaking-changes-super-in-non-class-methods">

### `super` in non-class methods

In CoffeeScript 1.x it is possible to use `super` in more than just class methods, such as in manually prototype-assigned functions:

> ```coffee
```coffee
A = ->
B = ->
B extends A
B.prototype.foo = -> super arguments... # Throws a compiler error
B.prototype.foo = -> super arguments...
# Throws a compiler error
```

Due to the switch to ES2015 `super`, this is no longer supported. The above case could be refactored to:
Expand All @@ -93,13 +117,26 @@ or
codeFor('breaking_change_super_in_non-class_methods_refactor_with_class')
```

</section>
<section id="breaking-changes-dynamic-class-keys-exclude-executable-class-scope">

### Dynamic class keys exclude executable class scope

Due to the hoisting required to compile to ES2015 classes, dynamic keys in class methods can’t use values from the executable class body unless the methods are assigned in prototype style.

> ```coffee
```coffee
class A
name = 'method'
"#{name}": -> # This method will be named 'undefined'
@::[name] = -> # This will work; assigns to `A.prototype.method`
```

</section>

<section id="breaking-changes-literate-coffeescript">

### Literate CoffeeScript now parsed by a Markdown library

The CoffeeScript 1.x implementation of Literate CoffeeScript relies on indentation to tell apart code blocks from documentation, and as such it can get confused by Markdown features that also use indentation like lists. In CoffeeScript 2 this has been refactored to now use [Markdown-It](https://github.com/markdown-it/markdown-it) to detect Markdown sections rather than just looking at indentation. The only significant difference is that now if you want to include a code block in documentation, as opposed to the compiler recognizing that code block as code, it must have at least one line fully unindented. Wrapping it in HTML tags is no longer sufficient.

Code blocks interspersed with lists may need to be refactored. In general, code blocks should be separated by a blank line between documentation, and should maintain a consistent indentation level—so an indentation of one tab (or whatever you consider to be a tab stop, like 2 spaces or 4 spaces) should be treated as your code’s “left margin,” with all code in the file relative to that column.
11 changes: 11 additions & 0 deletions documentation/sections/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
## Change Log

```
releaseHeader('2017-04-14', '2.0.0-beta1', '2.0.0-alpha1')
```

* Initial beta release of CoffeeScript 2. No further breaking changes are anticipated.
* Destructured objects and arrays now output using ES2015+ syntax whenever possible.
* Literate CoffeeScript now has much better support for parsing Markdown, thanks to using [Markdown-It](https://github.com/markdown-it/markdown-it) to detect Markdown sections rather than just looking at indentation.
* Calling a function named `get` or `set` now requires parentheses, to disambiguate from the `get` or `set` keywords (which are [disallowed](#unsupported-get-set)).
* The compiler now requires Node 7.6+, the first version of Node to support asynchronous functions without requiring a flag.


```
releaseHeader('2017-02-21', '2.0.0-alpha1', '1.12.4')
```
Expand Down
2 changes: 1 addition & 1 deletion documentation/sections/coffeescript_2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Since the CoffeeScript 2 compiler outputs ES2015+ syntax, it is your responsibil

There are many great task runners for setting up JavaScript build chains, such as [Gulp](http://gulpjs.com/), [Webpack](https://webpack.github.io/), [Grunt](https://gruntjs.com/) and [Broccoli](http://broccolijs.com/). If you’re looking for a very minimal solution to get started, you can use [babel-preset-env](https://babeljs.io/docs/plugins/preset-env/) and the command line:

> ```bash
```bash
npm install --global coffeescript@next
npm install --save-dev coffeescript@next babel-cli babel-preset-env
coffee -p *.coffee | babel --presets env > app.js
Expand Down
4 changes: 2 additions & 2 deletions documentation/sections/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ The command-line version of `coffee` is available as a [Node.js](http://nodejs.o

To install, first make sure you have a working copy of the latest stable version of [Node.js](http://nodejs.org/). You can then install CoffeeScript globally with [npm](http://npmjs.org):

> ```
```bash
npm install --global coffeescript@next
```

When you need CoffeeScript as a dependency of a project, within that project’s folder you can install it locally:

> ```
```bash
npm install --save coffeescript@next
```
2 changes: 1 addition & 1 deletion documentation/sections/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ The golden rule of CoffeeScript is: _“It’s just JavaScript.”_ The code com

**Latest Version:** [<%= fullVersion %>](http://github.com/jashkenas/coffeescript/tarball/<%= fullVersion %>)

> ```
```bash
npm install -g coffeescript@next
```
134 changes: 15 additions & 119 deletions documentation/sections/operators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,125 +24,21 @@ codeFor('modulo')

All together now:

<table class="definitions">

<tbody>

<tr>

<th>CoffeeScript</th>

<th>JavaScript</th>

</tr>

<tr>

<td>`is`</td>

<td>`===`</td>

</tr>

<tr>

<td>`isnt`</td>

<td>`!==`</td>

</tr>

<tr>

<td>`not`</td>

<td>`!`</td>

</tr>

<tr>

<td>`and`</td>

<td>`&&`</td>

</tr>

<tr>

<td>`or`</td>

<td>`||`</td>

</tr>

<tr>

<td>`true`, `yes`, `on`</td>

<td>`true`</td>

</tr>

<tr>

<td>`false`, `no`, `off`&emsp;</td>

<td>`false`</td>

</tr>

<tr>

<td>`@`, `this`</td>

<td>`this`</td>

</tr>

<tr>

<td>`of`</td>

<td>`in`</td>

</tr>

<tr>

<td>`in`</td>

<td>_<small>no JS equivalent</small>_</td>

</tr>

<tr>

<td>`a ** b`</td>

<td>`Math.pow(a, b)`</td>

</tr>

<tr>

<td>`a // b`</td>

<td>`Math.floor(a / b)`</td>

</tr>

<tr>

<td>`a %% b`</td>

<td>`(a % b + b) % b`</td>

</tr>

</tbody>

</table>
| CoffeeScript | JavaScript |
| --- | --- |
| `is` | `===` |
| `isnt` | `!==` |
| `not` | `!` |
| `and` | `&&` |
| `or` | `||` |
| `true`, `yes`, `on` | `true` |
| `false`, `no`, `off`&emsp; | `false` |
| `@`, `this` | `this` |
| `of` | `in` |
| `in` | _no JS equivalent_ |
| `a ** b` | `Math.pow(a, b)` |
| `a // b` | `Math.floor(a / b)` |
| `a %% b` | `(a % b + b) % b` |

```
codeFor('aliases')
Expand Down
Loading