Language tour example tests + Travis test job setup

- See `examples/README.md` for details. Essentially, `examples` is now a Dart package from which all sample tests will be run.
- A few tests are run in chrome, so Travis setup has been adapted so that chrome is installed and configured to run tests.
- Also added highlights to some code excerpts (more will be added later).

**Note**: Eventually the "original" example sources (`examples/language_tour ` and `examples/library_tour `) will be deleted, once we are sure that all relevant parts (including some that are only in Gists) have been integrated into the new package.

Contributes to #407 and #416.

.travis.yml

@@ -5,13 +5,17 @@ cache:
   directories:
   # - $HOME/[path]
 rvm: 2.4.2
+addons:
+  chrome: stable
 
 env:
   global:
+    - DISPLAY=:99.0
     - JEKYLL_ENV=production
     - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
   matrix:
     - TASK=./scripts/dartfmt.sh
+    - TASK=./scripts/analyze-and-test-examples.sh
     - TASK=./deploy/cibuild
 
 before_install:
@@ -23,6 +27,9 @@ install:
   - ./scripts/install.sh
   - ./scripts/write-ci-info.sh -v
 
+before_script:
+  - ./scripts/browser.sh
+
 script:
   - $TASK
 

examples/.gitignore

@@ -0,0 +1,9 @@
+# Files and directories created by pub
+.packages
+.pub/
+build/
+# Remove the following pattern if you wish to check in your lock file
+pubspec.lock
+
+# Directory created by dartdoc
+doc/api/

examples/README.md

@@ -0,0 +1,71 @@
+# Examples
+
+This package contains all of the sources that appear in the Language Tour and the Library Tour, including the smallest of code excerpts.
+
+## Original sources
+
+Sources originally taken from the Up-and-Running repo (but reworked to contain doc regions)
+are in these folders:
+
+- `language_tour` (now obsolete, see below)
+- `library_tour`
+
+These original sources don't have tests, and practically each code excerpt is an independent
+package (with its own pubspec).
+
+## New sources
+
+Consolidated and reworked versions of the original sources are being developed.
+So far, the Language Tour sources have been completely rewritten, and are found
+in these folders:
+
+- `lib/language_tour`
+- `test/language_tour`
+
+As can be expected, Travis jobs run the
+
+- Analyzer over both `lib` and `test`
+- Tests under `test`
+
+### Source organisation
+
+The new Language Tour sources are under `lib/language_tour` and `test/language_tour`.
+Below each of these folders, you'll find either a file or a folder with a name
+that matches a top-level section of the Language Tour. This file/folder contains
+all of the code excerpt sources for that section.
+
+Under `lib` you might find a function defined as:
+
+```dart
+void miscDeclAnalyzedButNotTested(bool c) {
+  {
+    // #docregion foo-1
+    var foo = 1
+    // #enddocregion foo-1
+  }
+
+  {
+    // #docregion foo-2
+    var foo = 2
+    // #enddocregion foo-2
+  }
+
+  // ...
+}
+```
+
+That is, code regions are placed with a (headless) code block. This ensures
+that code region declarations (which somethings re-declare the same entity)
+don't clash.
+
+### Where to find a code excerpt
+
+Generally speaking, a small code excerpt that is subject to testing is embedded
+directly in its test. Code regions that are subject to analysis only
+are in `lib`. Larger examples are in `lib`, and their tests (if any) under `test`.
+
+### Why not test all?
+
+Not all code excerpts are tested because some are just fragments of anything
+useful, and others illustrate features that would required significant test
+scaffolding to be written and the effort isn't worth the small gain.

examples/analysis_options.yaml

@@ -3,8 +3,9 @@
 
 analyzer:
   strong-mode: true
-#   exclude:
-#     - path/to/excluded/files/**
+  exclude:
+    - language_tour/**
+    - library_tour/**
 
 linter:
   rules:

examples/lib/language_tour/async.dart

@@ -0,0 +1,81 @@
+// ignore_for_file: unused_element, unused_local_variable
+import 'dart:async';
+
+typedef Async0 = Future Function();
+typedef Async1 = Future Function(dynamic);
+typedef Async2 = Future Function(dynamic, dynamic);
+
+Future miscDeclAnalyzedButNotTested() async {
+  // #docregion async-lookUpVersion
+  Future<String> lookUpVersion() async => '1.0.0';
+  // #enddocregion async-lookUpVersion
+
+  {
+    // #docregion await-lookUpVersion
+    await lookUpVersion();
+    // #enddocregion await-lookUpVersion
+  }
+
+  {
+    // #docregion checkVersion
+    Future checkVersion() async {
+      var version = await lookUpVersion();
+      // Do something with version
+    }
+    // #enddocregion checkVersion
+  }
+
+  {
+    var version;
+    // #docregion try-catch
+    try {
+      version = await lookUpVersion();
+    } catch (e) {
+      // React to inability to look up the version
+    }
+    // #enddocregion try-catch
+  }
+
+  {
+    // #docregion sync-lookUpVersion
+    String lookUpVersion() => '1.0.0';
+    // #enddocregion sync-lookUpVersion
+  }
+
+  {
+    Async0 findEntrypoint;
+    Async1 flushThenExit;
+    Async2 runExecutable;
+    var args;
+    // #docregion repeated-await
+    var entrypoint = await findEntrypoint();
+    var exitCode = await runExecutable(entrypoint, args);
+    await flushThenExit(exitCode);
+    // #enddocregion repeated-await
+  }
+
+  {
+    Future checkVersion() async {}
+    // #docregion main
+    Future main() async {
+      checkVersion();
+      print('In main: version is ${await lookUpVersion()}');
+    }
+    // #enddocregion main
+  }
+
+  {
+    // Excerpt from dart-tutorials-samples/httpserver/number_thinker.dart
+    Stream requestServer;
+    Async1 handleRequest;
+    // #docregion number_thinker
+    Future main() async {
+      // ...
+      await for (var request in requestServer) {
+        handleRequest(request);
+      }
+      // ...
+    }
+    // #enddocregion number_thinker
+  }
+}