Improve docs about why we pin analyzer (#3254)

packages/flutter_test/pubspec.yaml

@@ -1,9 +1,15 @@
 name: flutter_test
 dependencies:
-  test: 0.12.13
   quiver: ^0.21.4
 
-  # Not needed directly but transitively included due to package:test.
+  # The flutter tools depend on very specific internal implementation
+  # details of the 'test' package, which change between versions, so
+  # here we pin it precisely to avoid version skew across our packages.
+  test: 0.12.13
+
+  # We don't actually depend on 'analyzer', but 'test' does. We pin the
+  # version of analyzer we depend on to avoid version skew across our
+  # packages.
   analyzer: 0.27.2
 
   flutter:

packages/flutter_tools/pubspec.yaml

@@ -25,21 +25,15 @@ dependencies:
   flx:
     path: ../flx
 
-  test: 0.12.13 # see note below
+  # We depend on very specific internal implementation details of the
-  analyzer: '0.27.2' # see note below
+  # 'test' package, which change between versions, so here we pin it
+  # precisely.
+  test: 0.12.13
 
-# A note about 'test':
+  # We don't actually depend on 'analyzer', but 'test' does. We pin the
-# We depend on very specific internal implementation details of the
+  # version of analyzer we depend on to avoid version skew across our
-# 'test' package, which change between versions, so here we pin it
+  # packages.
-# precisely.
+  analyzer: 0.27.2
-
-# A note about 'analyzer':
-# We don't actually depend on 'analyzer', but 'test' does. We aren't
-# compatible with some older versions of 'analyzer'. We lie here,
-# saying we do depend on it, so that we constrain the version that
-# 'test' will get to a version that we'll probably be ok with. (This
-# is why there's no upper bound on our dependency.)
-# See also https://github.com/dart-lang/pub/issues/1356
 
 dev_dependencies:
   mockito: ^0.11.0