test: add library doc comments (#2586)

Author: kevmoo

pkgs/test/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.29.1-wip
+
+* Add comments to the top-level libraries in the package.
+
 ## 1.29.0
 
 * Add `--coverage-package` flag, which filters the coverage report to specific

pkgs/test/lib/expect.dart

@@ -2,4 +2,10 @@
 // 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.
 
+/// The `expect` API for test assertions.
+///
+/// This is a re-export of `package:matcher/expect.dart`.
+/// Generally you should import `package:test/test.dart` instead.
+library;
+
 export 'package:matcher/expect.dart';

pkgs/test/lib/fake.dart

@@ -6,5 +6,11 @@
 // so until Mockito stops implementing its own version of `Fake`, because there
 // is code in the wild that imports both test_api.dart and Mockito.
 
+/// The `Fake` class for faking dependencies.
+///
+/// This is a re-export of `package:test_api/fake.dart`. It is kept separate
+/// to avoid a breaking change for users who import `package:mockito` directly.
+library;
+
 // ignore: deprecated_member_use
 export 'package:test_api/fake.dart';

pkgs/test/lib/scaffolding.dart

@@ -2,4 +2,11 @@
 // 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.
 
+/// The core APIs for defining the structure of a test suite.
+///
+/// This library avoids exports of the `package:matcher` APIs from
+/// `package:test/expect.dart` and can be used with alternative expectation
+/// frameworks like `package:checks`.
+library;
+
 export 'package:test_core/src/scaffolding.dart';

pkgs/test/lib/test.dart

@@ -2,6 +2,16 @@
 // 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.
 
+/// The main test library.
+///
+/// This library exports the core test APIs, including `test()`, `group()`,
+/// `setUp()`, `tearDown()`, and `expect()`.
+///
+/// This is the recommended import for most test files.
+/// If you want to use `package:checks` for assertions, import
+/// `package:test/scaffolding.dart` instead.
+library;
+
 export 'package:matcher/expect.dart';
 // Deprecated exports not surfaced through focused libraries.
 // ignore: deprecated_member_use

pkgs/test/pubspec.yaml

@@ -1,5 +1,5 @@
 name: test
-version: 1.29.0
+version: 1.29.1-wip
 description: >-
   A full featured library for writing and running Dart tests across platforms.
 repository: https://github.com/dart-lang/test/tree/master/pkgs/test