search

dart-lang / api.dart.dev

Dart API docs
https://api.dart.dev
BSD 3-Clause "New" or "Revised" License
19 stars 17 forks source link

dart:cli documentation is missing #81

Closed Hixie closed 2 years ago

Hixie commented 3 years ago

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 commented 3 years ago

CC: @kwalrath

kwalrath commented 3 years ago

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

kwalrath commented 3 years ago

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

devoncarew commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

cc @leafpetersen

Hixie commented 3 years ago

(see also https://github.com/dart-lang/sdk/issues/39390)

aam commented 3 years ago

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

mit-mit commented 3 years ago

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

mit-mit commented 2 years ago

This was fixed a while back