add import guidance to library-level docs (#3530)

* add import guidance to library-level docs

* add import docs to other packages

* fix review comment

* clarify which libraries aren't meant to be directly imported

packages/cassowary/lib/cassowary.dart

@@ -3,6 +3,9 @@
 // found in the LICENSE file.
 
 /// An implementation of the Cassowary constraint solving algorithm in Dart.
+/// 
+/// This library is not meant to be imported by developers.
+/// It will soon be integrated into another Flutter library.
 ///
 /// This is used by the [RenderAutoLayout] render object in the rendering
 /// library and by the [AutoLayout] widget in the widget library.

packages/flutter/lib/animation.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter animation system.
+/// 
+/// To use, import `package:flutter/animation.dart`.
 ///
 /// See [flutter.io/animations](https://flutter.io/animations/) for an overview.
 ///

packages/flutter/lib/gestures.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter gesture recognizers.
+/// 
+/// To use, import `package:flutter/gestures.dart`.
 library gestures;
 
 export 'src/gestures/arena.dart';

packages/flutter/lib/http.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// A [Future]-based library for making HTTP requests.
+/// 
+/// To use, import `package:flutter/http.dart`.
 ///
 /// This library is based on Dart's `http` package, but differs in that it is a
 /// `mojo`-based HTTP client and does not have a dependency on mirrors.

packages/flutter/lib/material.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// Flutter widgets implementing Material Design.
+/// 
+/// To use, import `package:flutter/material.dart`.
 ///
 /// See
 /// [www.google.com/design/spec/material-design](https://www.google.com/design/spec/material-design/introduction.html)

packages/flutter/lib/painting.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter painting library.
+/// 
+/// To use, import `package:flutter/painting.dart`.
 ///
 /// This library includes a variety of classes that wrap the Flutter
 /// engine's painting API for more specialised purposes, such as painting scaled

packages/flutter/lib/rendering.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter rendering tree.
+/// 
+/// To use, import `package:flutter/rendering.dart`.
 ///
 /// The [RenderObject] hierarchy is used by the Flutter Widgets
 /// library to implement its layout and painting back-end. Generally,

packages/flutter/lib/scheduler.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter Scheduler library.
+/// 
+/// To use, import `package:flutter/scheduler.dart`.
 ///
 /// This library is responsible for scheduler frame callbacks, and tasks at
 /// given priorities.

packages/flutter/lib/services.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// System services exposed to Flutter apps.
+/// 
+/// To use, import `package:flutter/services.dart`.
 ///
 /// For example, this library includes [fetch], which fetches data from the
 /// network.

packages/flutter/lib/widgets.dart

@@ -3,6 +3,8 @@
 // found in the LICENSE file.
 
 /// The Flutter widget framework.
+/// 
+/// To use, import `package:flutter/widgets.dart`.
 library widgets;
 
 export 'src/widgets/app.dart';

packages/newton/lib/newton.dart

@@ -4,6 +4,9 @@
 
 /// Simple one-dimensional physics simulations, such as springs, friction, and
 /// gravity, for use in user interface animations.
+/// 
+/// This library is not meant to be imported by developers.
+/// It will soon be integrated into another Flutter library.
 library newton;
 
 export 'src/clamped_simulation.dart';