Lint JavaScript snippets in the documentation

.eslintignore

@@ -1,4 +1,3 @@
-/documentation/
 /images/
 /build/
 /vendor/

documentation/.eslintrc.js

@@ -0,0 +1,14 @@
+module.exports = {
+  root: false,
+  plugins: ['markdown'],
+  rules: {
+    // Some snippets reference variables from previous ones
+    // but eslint-plugin-markdown lints them independently.
+    // Disable the rules that this causes trouble with:
+    'no-unused-vars': 0,
+    'no-undef': 0
+  },
+  parserOptions: {
+    sourceType: 'script' // Otherwise globalReturn won't work, we use that for the async snippets
+  }
+};

documentation/api/UnexpectedError.md

@@ -18,7 +18,8 @@ shortcut you can also just pass the output or format directly.
 An alternative to calling `getErrorMessage(output)` with an output,
 you can append the error message to an output the following way:
 
-```js#evaluate:false
+<!-- unexpected-markdown evaluate:false -->
+```js
 output.appendErrorMessage(error);
 ```
 

documentation/api/addAssertion.md

@@ -2,7 +2,9 @@
 
 Signature:
 
-```js#evaluate:false
+<!-- unexpected-markdown evaluate:false -->
+<!-- eslint-skip -->
+```js
 expect.addAssertion(pattern, handler);
 expect.addAssertion([pattern, ...]], handler);
 ```
@@ -63,15 +65,18 @@ type and pattern of the assertion.
 
 So in this case, when `expect` is called the following way:
 
-```js#evaluate:false
-expect([3,2,1], 'to be sorted', reverse);
+<!-- unexpected-markdown evaluate:false -->
+```js
+expect([3, 2, 1], 'to be sorted', reverse);
 ```
 
 The handler to our assertion will be called with the values the
 following way, where the _not_ flag in the nested expect will be
 removed:
 
-```js#evaluate:false
+<!-- unexpected-markdown evaluate:false -->
+<!-- eslint-skip -->
+```js
 expect.addAssertion('<array> [not] to be (sorted|ordered) <function?>', function(expect, [3,2,1], reverse){
     expect([3,2,1], '[not] to equal', [].concat([3,2,1]).sort(reverse));
 });
@@ -286,8 +291,13 @@ It would be pretty nice if we could use
 even if the retrieval is delayed. Then we would be able to do stuff
 like this:
 
-```js#evaluate:false
-return expect(new Timelock('Hello world'), 'to satisfy', expect.it('have length', 11));
+<!-- unexpected-markdown evaluate:false -->
+```js
+return expect(
+  new Timelock('Hello world'),
+  'to satisfy',
+  expect.it('have length', 11)
+);
 ```
 
 First we need to define a [type](../addType/) for handling the `Timelock`:
@@ -322,8 +332,13 @@ expect.addAssertion('<Timelock> to satisfy <any>', function(
 
 Let's see how it works:
 
-```js#async:true
-return expect(new Timelock('Hello world!', 5), 'to satisfy', expect.it('not to match', /!/));
+<!-- unexpected-markdown async:true -->
+```js
+return expect(
+  new Timelock('Hello world!', 5),
+  'to satisfy',
+  expect.it('not to match', /!/)
+);
 ```
 
 ```output

documentation/api/addType.md

@@ -94,20 +94,22 @@ That is already quite helpful, but it would be even nicer if the
 stringification of `Person` instances could read as valid calls to the
 constructor. We can fix that by implementing an `inspect` method on the type.
 
-```js#freshExpect:true
+<!-- unexpected-markdown freshExpect:true -->
+```js
 expect.addType({
-    name: 'Person',
-    base: 'object',
-    identify: function (value) {
-        return value instanceof Person;
-    },
-    inspect: function (person, depth, output, inspect) {
-       output.text('new Person(')
-             .append(inspect(person.name, depth))
-             .text(', ')
-             .append(inspect(person.age, depth))
-             .text(')');
-    }
+  name: 'Person',
+  base: 'object',
+  identify: function(value) {
+    return value instanceof Person;
+  },
+  inspect: function(person, depth, output, inspect) {
+    output
+      .text('new Person(')
+      .append(inspect(person.name, depth))
+      .text(', ')
+      .append(inspect(person.age, depth))
+      .text(')');
+  }
 });
 ```
 
@@ -147,50 +149,58 @@ same depth to the `inspect` function.
 Let's say we wanted `Person` instances only to be compared by name and not by
 age. Then we need to override the `equal` method:
 
-```js#freshExpect:true
+<!-- unexpected-markdown freshExpect:true -->
+```js
 expect.addType({
-    name: 'Person',
-    base: 'object',
-    identify: function (value) {
-        return value instanceof Person;
-    },
-    inspect: function (person, depth, output, inspect) {
-       output.text('new Person(')
-             .append(inspect(person.name, depth))
-             .text(', ')
-             .append(inspect(person.age, depth))
-             .text(')');
-    },
-    equal: function (a, b, equal) {
-        return a === b || equal(a.name, b.name);
-    }
+  name: 'Person',
+  base: 'object',
+  identify: function(value) {
+    return value instanceof Person;
+  },
+  inspect: function(person, depth, output, inspect) {
+    output
+      .text('new Person(')
+      .append(inspect(person.name, depth))
+      .text(', ')
+      .append(inspect(person.age, depth))
+      .text(')');
+  },
+  equal: function(a, b, equal) {
+    return a === b || equal(a.name, b.name);
+  }
 });
 ```
 
 This will produce the same output as above, but that means the diff if
 wrong. It states that the age should be changed. We can fix that the
 following way:
 
-```js#freshExpect:true
+<!-- unexpected-markdown freshExpect:true -->
+```js
 expect.addType({
-    name: 'Person',
-    base: 'object',
-    identify: function (value) {
-        return value instanceof Person;
-    },
-    inspect: function (person, depth, output, inspect) {
-       output.text('new Person(')
-             .append(inspect(person.name, depth))
-             .text(', ')
-             .append(inspect(person.age, depth))
-             .text(')');
-    },
-    equal: function (a, b, equal) {
-        return a === b || equal(a.name, b.name);
-    },
-    diff: function (actual, expected, output, diff, inspect) {
-        return this.baseType.diff({name: actual.name}, {name: expected.name}, output);
-    }
+  name: 'Person',
+  base: 'object',
+  identify: function(value) {
+    return value instanceof Person;
+  },
+  inspect: function(person, depth, output, inspect) {
+    output
+      .text('new Person(')
+      .append(inspect(person.name, depth))
+      .text(', ')
+      .append(inspect(person.age, depth))
+      .text(')');
+  },
+  equal: function(a, b, equal) {
+    return a === b || equal(a.name, b.name);
+  },
+  diff: function(actual, expected, output, diff, inspect) {
+    return this.baseType.diff(
+      { name: actual.name },
+      { name: expected.name },
+      output
+    );
+  }
 });
 ```
 
@@ -218,53 +228,62 @@ on the base directly when you know it is the one you need.
 
 You could also do something really custom as seen below:
 
-```js#freshExpect:true
+<!-- unexpected-markdown freshExpect:true -->
+```js
 var inlineDiff = true; // used to change inlining in a later example
 
 expect.addType({
-    name: 'Person',
-    base: 'object',
-    identify: function (value) {
-        return value instanceof Person;
-    },
-    inspect: function (person, depth, output, inspect) {
-       output.text('new Person(')
-             .append(inspect(person.name, depth))
-             .text(', ')
-             .append(inspect(person.age, depth))
-             .text(')');
-    },
-    equal: function (a, b, equal) {
-        return a === b || equal(a.name, b.name);
-    },
-    diff: function (actual, expected, output, diff, inspect) {
-        output.inline = inlineDiff;
-        var nameDiff = diff(actual.name, expected.name);
-
-        output.text('new Person(')
-              .nl()
-              .indentLines();
-
-        if (nameDiff && nameDiff.inline) {
-            output.append(nameDiff);
-        } else {
-            output.i().append(inspect(actual.name)).text(',').sp()
-                  .annotationBlock(function () {
-                      this.error('should be ').append(inspect(expected.name));
-                      if (nameDiff) {
-                          this.nl().append(nameDiff);
-                      }
-                  })
-                  .nl();
-        }
-
-        output.i().append(inspect(actual.age))
-              .outdentLines()
-              .nl()
-              .text(')');
-
-        return output;
+  name: 'Person',
+  base: 'object',
+  identify: function(value) {
+    return value instanceof Person;
+  },
+  inspect: function(person, depth, output, inspect) {
+    output
+      .text('new Person(')
+      .append(inspect(person.name, depth))
+      .text(', ')
+      .append(inspect(person.age, depth))
+      .text(')');
+  },
+  equal: function(a, b, equal) {
+    return a === b || equal(a.name, b.name);
+  },
+  diff: function(actual, expected, output, diff, inspect) {
+    output.inline = inlineDiff;
+    var nameDiff = diff(actual.name, expected.name);
+
+    output
+      .text('new Person(')
+      .nl()
+      .indentLines();
+
+    if (nameDiff && nameDiff.inline) {
+      output.append(nameDiff);
+    } else {
+      output
+        .i()
+        .append(inspect(actual.name))
+        .text(',')
+        .sp()
+        .annotationBlock(function() {
+          this.error('should be ').append(inspect(expected.name));
+          if (nameDiff) {
+            this.nl().append(nameDiff);
+          }
+        })
+        .nl();
     }
+
+    output
+      .i()
+      .append(inspect(actual.age))
+      .outdentLines()
+      .nl()
+      .text(')');
+
+    return output;
+  }
 });
 ```
 

documentation/api/expect.md

@@ -26,9 +26,10 @@ does some unholy trickery so it also works in Jasmine.
 Note that if the assertion is asynchronous, you'll have to return the promise
 to the `it` block:
 
-```js#eval:false
-it('should call the callback', function () {
-    return expect(setImmediate, 'to call the callback');
+<!-- unexpected-markdown evaluate:false -->
+```js
+it('should call the callback', function() {
+  return expect(setImmediate, 'to call the callback');
 });
 ```
 
@@ -52,8 +53,9 @@ expect('abc', 'to be a string').and('to have length', 3);
 Again, note that you need to return the value returned by `expect` to your `it`
 block if any of the assertions are asynchronous:
 
-```js#eval:false
-it('should do the right thing', function () {
-    return expect(setImmediate, 'to be a function').and('to call the callback');
+<!-- unexpected-markdown evaluate: false -->
+```js
+it('should do the right thing', function() {
+  return expect(setImmediate, 'to be a function').and('to call the callback');
 });
 ```