From dc9b1430617881889e6ce06d7e0f1e4e2091a9fb Mon Sep 17 00:00:00 2001
From: Rene Rivera <grafikrobot@gmail.com>
Date: Thu, 17 Nov 2016 13:24:58 -0600
Subject: [PATCH] Clean up and document Travis setup.

---
 .travis.yml | 58 +++++++++++++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 20 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 81dd22b..ac8bf4d 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,52 +4,68 @@
 #
 # Copyright Rene Rivera 2015-2016.
 
-branches:
-  only:
-    - master
-    - develop
-
-dist: trusty
-
-language: generic
-
+# Setting up notifications like this is optional as the default behavior
+# of Travis is to notify the commiter of problems. But setting a specific
+# recipient this way ensures you get all the communications about the
+# builds.
 notifications:
   email:
     recipients:
       - grafikrobot@gmail.com
 
+# For now the CI scripts only support the two main branches available
+# on the boost super-project.
+branches:
+  only:
+    - master
+    - develop
+
+# We specify a generic language instead of C++ as Travis sets up
+# additional environment vars that point to its default toolset
+# instead of the one we install. The extra env doesn't interfere,
+# but at the same time it's misleading. So to avoid confusion and
+# possible unseen side effects we stick with no C++ default setup.
+language: generic
+
+# Speficy the default as Linux here, to avoid duplication in the matrix
+# below. We use Trausty as that's the latest we can use. And it's better
+# supported by the whole range of C++ toolsets we like to test on.
+dist: trusty
+os: linux
+
+# Because we install our own toolsets and other software we need
+# to run the sudo support.
 sudo: required
 
+# Travis has a long standing bug with their rather complicated
+# build matrix evaluation that causes empty jobs to be created.
+# This global matrix entry in combination with the exclusion
+# below works around that bug. This is the suggested fix from
+# the Travis support people.
 env:
   matrix:
     - TRAVIS_EMPTY_JOB_WORKAROUND=true
 
+# This lists all the toolsets we will test with the Boost CI
+# scripts. Predef needs to check all of them as its job is to
+# distiguish between all of them. For other libraries you would
+# want to limit the list to the toolsets that are important
+# for that.
 matrix:
   exclude:
     - env: TRAVIS_EMPTY_JOB_WORKAROUND=true
   include:
     - env: TOOLSET=clang-3.4
-      os: linux
     - env: TOOLSET=clang-3.5
-      os: linux
     - env: TOOLSET=clang-3.6
-      os: linux
     - env: TOOLSET=clang-3.7
-      os: linux
     - env: TOOLSET=clang-3.8
-      os: linux
     - env: TOOLSET=clang-3.9
-      os: linux
     - env: TOOLSET=gcc-4.7
-      os: linux
     - env: TOOLSET=gcc-4.8
-      os: linux
     - env: TOOLSET=gcc-4.9
-      os: linux
     - env: TOOLSET=gcc-5
-      os: linux
     - env: TOOLSET=gcc-6
-      os: linux
     - env: TOOLSET=xcode-6.1
       os: osx
     - env: TOOLSET=xcode-6.2
@@ -77,6 +93,8 @@ matrix:
       os: osx
       osx_image: xcode8
 
+# These are the standard steps to bootstrap the Boost CI scripts
+# and to forward the actions to the scripts.
 before_install:
   # Fetch the scripts to do the actual building/testing.
   - |