tests: explain and test dependency flattening routines (#11993)

- Add comments to explain that `install_dependency_symlinks` and `flatten_dependencies` are actually used.
- Add a test that exercises the routines.

var/spack/repos/builtin.mock/packages/flatten-deps/package.py

@@ -0,0 +1,19 @@
+# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+from spack import *
+
+
+class FlattenDeps(Package):
+    """Example install that flattens dependencies."""
+
+    homepage = "http://www.example.com"
+    url      = "http://www.example.com/a-1.0.tar.gz"
+
+    version('1.0', '0123456789abcdef0123456789abcdef')
+
+    depends_on('dependency-install')
+
+    install = install_dependency_symlinks