Enable API docs for dart:cli

Clarify this is supported, but deprecated, and may get removed
in the future should we find a suitable replacement.

Bug: dart-archive/api.dart.dev#81
Bug: #39390
Change-Id: I1304a0862986ae1b365a063ee75f0041341523f5
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/214620
Commit-Queue: Michael Thomsen <[email protected]>
Reviewed-by: Lasse R.H. Nielsen <[email protected]>

Author: mit-mit

sdk/lib/cli/cli.dart

@@ -3,7 +3,6 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// {@category VM}
-/// {@nodoc}
 @Deprecated(
     "The functionality of this library is incomplete and may be removed in a later version")
 library dart.cli;

sdk/lib/cli/wait_for.dart

@@ -69,7 +69,32 @@ class _WaitForUtils {
  * Suspends the stack, runs microtasks, and handles incoming events until
  * [future] completes.
  *
- * WARNING: EXPERIMENTAL. USE AT YOUR OWN RISK.
+ * ## Deprecation notice
+ *
+ * The `waitFor` feature is deprecated.
+ * The feature was intended to solve a particular problem for existing code,
+ * a problem introduced by a breaking change to the platform libraries.
+ * The `waitFor` function is not suitable for general use.
+ * The feature has shortcomings that can affect other code
+ * running in the same isolate, including:
+ *  * A function call that looks synchronous may cause other asynchronous
+ *    events to run before it returns.
+ *    This is something synchronous code can usually assume not to happen,
+ *    and some code may have been written to take advantage of that
+ *    assumed behavior. Such code can fail in unexpected ways.
+ *  * Multiple nested calls to `waitFor` may block each other
+ *    since the most recent call always needs to complete
+ *    before any other call can complete.
+ *    Judicious use of `waitFor` is necessary to avoid unexpected deadlocks
+ *    which wouldn't happen if using `await` instead.
+ *    If more than one library in the same program is using `waitFor`,
+ *    then it's hard to avoid or control whether such blocking will happen.
+ *
+ * The feature is not actively maintained.
+ * It will remain as-is to support the original problem it was added to solve,
+ * at least until that problem can be solved in some other way.
+ * 
+ * ## Call semantics
  *
  * This call does the following:
  * - While [future] is not completed:
@@ -111,30 +136,6 @@ class _WaitForUtils {
  * Please be aware that nesting calls to [waitFor] can lead to deadlock if
  * subsequent calls block waiting for a condition that is only satisfied when
  * an earlier call returns.
- *
- * **NOTICE**
- * The `waitFor` feature is deprecated.
- * The feature was intended to solve a particular problem for existing code,
- * a problem introduced by a breaking change to the platform libraries.
- * The `waitFor` function is not suitable for general use.
- * The feature has shortcomings that can affect other code
- * running in the same isolate, including:
- *  * A function call that looks synchronous may cause other asynchronous
- *    events to run before it returns.
- *    This is something synchronous code can usually assume not to happen,
- *    and some code may have been written to take advantage of that
- *    assumed behavior. Such code can fail in unexpected ways.
- *  * Multiple nested calls to `waitFor` may block each other
- *    since the most recent call always needs to complete
- *    before any other call can complete.
- *    Judicious use of `waitFor` is necessary to avoid unexpected deadlocks
- *    which wouldn't happen if using `await` instead.
- *    If more than one library in the same program is using `waitFor`,
- *    then it's hard to avoid or control whether such blocking will happen.
- *
- * The feature is not actively maintained.
- * It will remain as-is to support the original problem it was added to solve,
- * at least until that problem can be solved in some other way.
  */
 @Deprecated(
     "This functionality is incomplete and may be removed in a later version")