dart:cli documentation is missing

[Hixie]

The https://api.dart.dev/ documentation is missing the "dart:cli" package.
It still exists, as demonstrated by running this program:

import 'dart:cli';
void main() => print(waitFor);

It used to be documented, for example, you can Google around and find this: https://api.dart.dev/stable/2.1.0/dart-cli/dart-cli-library.html

[franklinyow]

CC: @kwalrath

[kwalrath]

Not sure whether this should be in the sdk repo or api.dart.dev repo... feel free to bounce it back. :)

[kwalrath]

@devoncarew who'd be a good person to take this on?

[devoncarew]

This is by design; dart:cli is just one method, w/ a bunch of controversy about whether we should have shipped a one-method top-level core library.

cc @mit-mit

I believe this is WIA.

[Hixie]

Having a secret method seems really weird. We should either decide we don't want this API and remove it, or we should document it, IMHO. Right now we're in a weird situation where the API exists and people ask questions about it but to answer their questions we have to point them to old API docs even though it still exists.

[mit-mit]

It's not secret, but it is experimental, hence it's not in the stable API docs.

I agree we should work towards either graduating it from being an experiment, or deprecate and then discontinue it.

[Hixie]

Right now it looks like a fully supported feature we forgot to document (or worse, which we did document but then the documentation broke). If we want to describe it as an experiment we should document it but say "this is experimental".

[Hixie]

I would like to escalate this. We should either document it or remove it but having undocumented features is IMHO not an acceptable middle ground.

[Hixie]

cc @leafpetersen

[Hixie]

(see also dart-lang/sdk#39390)

[aam]

https://dart-review.googlesource.com/c/sdk/+/210125 landed some time ago that did 'deprecate the dart:cli library and waitFor method.'

[mit-mit]

Updating in https://dart-review.googlesource.com/c/sdk/+/214620

[mit-mit]

This was fixed a while back