Clarify use of environment variables

Author: josevalim

lib/mix/lib/mix.ex

@@ -331,20 +331,20 @@ defmodule Mix do
     * `MIX_ARCHIVES` - specifies the directory into which the archives should be installed
       (default: `~/.mix/archives`)
 
-    * `MIX_BUILD_PATH` - sets the project `Mix.Project.build_path/0` config.
-      This option must always point to a subdirectory inside a temporary directory.
-      For instance, never "/tmp" or "_build" but "_build/PROD" or "/tmp/PROD", as
-      required by Mix. This environment variable is used mostly by external build
-      tools. For your CI servers, you likely want to use `MIX_BUILD_ROOT` below.
+    * `MIX_BUILD_PATH` - sets the project `Mix.Project.build_path/0`, including the
+      current environment, such as "/path/to/project/_build/dev". This environment
+      variable is used mostly by external build tools who need enforce a build
+      directory independent of `MIX_ENV` and `MIX_TARGET`. For your CI servers,
+      you likely want to use `MIX_BUILD_ROOT` below.
 
     * `MIX_BUILD_ROOT` - sets the root directory where build artifacts should be
-      written to. For example, "_build". If `MIX_BUILD_PATH` is set, this option
-      is ignored.
+      written to. For example, "/path/to/_build". If `MIX_BUILD_PATH` is set,
+      this option is ignored.
 
     * `MIX_DEBUG` - outputs debug information about each task before running it
 
     * `MIX_DEPS_PATH` - sets the project `Mix.Project.deps_path/0` config for the
-      current project (default: `deps`)
+      current project, as an absolute path, such as `/path/to/project/deps`
 
     * `MIX_ENV` - specifies which environment should be used. See [Environments](#module-environments)
 

lib/mix/lib/mix/project.ex

@@ -656,26 +656,23 @@ defmodule Mix.Project do
   (which defaults to `"_build"`) and a subdirectory. The subdirectory
   is built based on two factors:
 
-    * If `:build_per_environment` is set, the subdirectory is the value
-      of `Mix.env/0` (which can be set via `MIX_ENV`). Otherwise it is
-      set to "shared".
+    * If `:build_per_environment` is set (the default), the subdirectory
+      is the value of `Mix.env/0` (which can be set via `MIX_ENV`).
+      Otherwise it is set to "shared".
 
     * If `Mix.target/0` is set (often via the `MIX_TARGET` environment
       variable), it will be used as a prefix to the subdirectory.
 
-  Finally, the environment variables `MIX_BUILD_ROOT` and `MIX_BUILD_PATH`
-  can be used to change the result of this function. `MIX_BUILD_ROOT`
-  overwrites only the root `"_build"` directory while keeping the
-  subdirectory as is. It may be useful to change it for caching reasons,
-  typically during Continuous Integration (CI). `MIX_BUILD_PATH` overrides
-  the build path altogether and it typically used by other build tools
-  that invoke the `mix` CLI.
+  The behaviour of this function can be modified by two environment
+  variables, `MIX_BUILD_ROOT` and `MIX_BUILD_PATH`, see [the Mix
+  documentation for more information](Mix.html#environment-variables).
 
   > #### Naming differences {: .info}
   >
   > Ideally the configuration option `:build_path` would be called
-  > `:build_root`, as it would fully mirror the environment variable.
-  > However, its name is preserved for backwards compatibility.
+  > `:build_root`, as it only sets the root component of the build
+  > path but not the subdirectory. However, its name is preserved
+  > for backwards compatibility.
 
   ## Examples