Also add comments requested by review, and some more.

tests/standalone/packages_file_test.dart

 // Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 import "dart:async";
 import "dart:io";
 import "dart:convert" show JSON;
 import "package:path/path.dart" as p;
 import "package:async_helper/async_helper.dart";
 
 main() async {
   asyncStart();
 
+  // The `test` function can generate file or http resources.
+  // It replaces "%file/" with URI of the root directory of generated files and
+  // "%http/" with the URI of the HTTP server's root in appropriate contexts
+  // (all file contents and parameters).
+
+  // With no specified resolutiuon and no implicit .packages or packages/

[floitsch, 2016/05/27 14:11:19]

Resolution 

+  // available, nothing can be resolved and the package can't be imported.
   await test("file: no resolution",
     "%file/main.dart",
     file: {"main": testMain},
     expect: {"foo.x": null});
 
   // An HTTP script with no ".packages" file assumes a "packages" dir.
+  // All packages are resolved relative to that dir, whether it exists or not.
   await test("http: no resolution", "%http/main.dart",
     http: {"main": testMain},
     expect: {
       "iroot": "%http/packages/",
       // "foo": null,
       "foo/": "%http/packages/foo/",
       "foo/bar": "%http/packages/foo/bar",
       "foo.x": null,
     });
 
+  // A number of tests which behave similarly whether run as local files or
+  // over HTTP.
   for (var scheme in ["file", "http"]) {
 
+    /// Run a test in the current scheme.
+    ///
+    /// The files are served either through HTTP or in a local directory.
+    /// Use "%$scheme/" to refer to the root of the served files.
     testScheme(name, main, {expect, files, args, root, config}) {
       return test("$scheme: $name", main, expect: expect,
         root: root, config: config, args: args,
         file: scheme == "file" ? files : null,
         http: scheme == "http" ? files : null);
     }
 
     {
       var files = {"main": testMain, "packages": fooPackage};
       // Expect implicitly detected package dir.
       await testScheme("implicit packages dir","%$scheme/main.dart",
         files: files,
         expect: {
           "iroot": "%$scheme/packages/",
           // "foo": null,
           "foo/": "%$scheme/packages/foo/",
           "foo/bar": "%$scheme/packages/foo/bar",
         });
     }
 
     {
       var files = {"sub": {"main": testMain, "packages": fooPackage},
                    ".packages": ""};
       // Expect implicitly detected package dir.
+      // Should not detect the .packages file in parent directory.
+      // That file is empty, so if it is used, the system cannot resolve "foo".
       await testScheme("implicit packages dir 2", "%$scheme/sub/main.dart",
         files: files,
         expect: {
           "iroot": "%$scheme/sub/packages/",
           // "foo": null,
           "foo/": "%$scheme/sub/packages/foo/",
           "foo/bar": "%$scheme/sub/packages/foo/bar",
         });
     }
 
@@ skipping 57 matching lines @@
         expect: {
           "pconf": "%$scheme/.pkgs",
           "iconf": "%$scheme/.pkgs",
           // "foo": null,
           "foo/": "%$scheme/pkgs/foo/",
           "foo/bar": "%$scheme/pkgs/foo/bar",
         });
     }
 
     {
+      /// The package config can be specified as a data: URI.
+      /// (In that case, relative URI references in the config file won't work).
       var files = {"main": testMain,
                    ".packages": "foo:packages/foo/",
                    "packages": fooPackage,
                    "pkgs": fooPackage};
       var dataUri = "data:,foo:%$scheme/pkgs/foo/\n";
       await testScheme("explicit data: config file", "%$scheme/main.dart",
         files: files,
         config: dataUri,
         expect: {
           "pconf": dataUri,
           "iconf": dataUri,
           // "foo": null,
           "foo/": "%$scheme/pkgs/foo/",
           "foo/bar": "%$scheme/pkgs/foo/bar",
         });
     }
   }
 
   {
-    // With a file: URI, the lookup checks for a .packages file in superdirs.
+    // With a file: URI, the lookup checks for a .packages file in superdirs
+    // when it fails to find a ,packages file or packages/ directory next to
+    // the entry point.
     var files = {"sub": { "main": testMain },
                  ".packages": "foo:pkgs/foo/",
                  "pkgs": fooPackage};
     await test("file: implicit .packages file in ..", "%file/sub/main.dart",
       file: files,
       expect: {
         "iconf": "%file/.packages",
         // "foo": null,
         "foo/": "%file/pkgs/foo/",
         "foo/bar": "%file/pkgs/foo/bar",
       });
   }
 
   {
     // With a non-file: URI, the lookup assumes a packges/ dir.
+    // The absence of a .packages file next to the entry point means
+    // that the resolution assumes a packages directory, whether it exists or
+    // not. It should not find the .packages file in the parent directory.
     var files = {"sub": { "main": testMain },
                  ".packages": "foo:pkgs/foo/",
                  "pkgs": fooPackage};
-    // Expect implicitly detected .package file.
     await test("http: implicit packages dir", "%http/sub/main.dart",
       http: files,
       expect: {
         "iroot": "%http/sub/packages/",
         // "foo": null,
         "foo/": "%http/sub/packages/foo/",
         "foo/bar": "%http/sub/packages/foo/bar",
         "foo.x": null,
       });
   }
@@ skipping 11 matching lines @@
 
 var failingTests = new Set();
 
 var fileHttpRegexp = new RegExp(r"%(?:file|http)/");
 
 Future test(String name, String main,
             {String root, String config, List<String> args,
              Map file, Map http, Map expect}) async {
   // Default values that are easily recognized in output.
   String fileRoot = "<no files configured>";
-  String httpRoot = "<not http server configured>";
+  String httpRoot = "<no http server configured>";
 
   /// Replaces markers `%file/` and `%http/` with the actual locations.
   ///
   /// Accepts a `null` [source] and returns `null` again.
   String fixPaths(String source) {
     if (source == null) return null;
     var result = source.replaceAllMapped(fileHttpRegexp, (match) {
       if (source.startsWith("file", match.start + 1)) return fileRoot;
       return httpRoot;
     });
@@ skipping 253 matching lines @@
 }
 
 // Counter used to avoid reusing temporary directory names.
 // Some platforms are timer based, and creating two temp-dirs withing a short
 // duration may cause a collision.
 int tmpDirCounter = 0;
 
 Directory createTempDir() {
   return Directory.systemTemp.createTempSync("pftest-${tmpDirCounter++}-");
 }