Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the dart:collection API docs #13760

Closed
kwalrath opened this issue Oct 2, 2013 · 7 comments
Closed

Improve the dart:collection API docs #13760

kwalrath opened this issue Oct 2, 2013 · 7 comments
Labels
area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. core-a library-collection type-documentation A request to add or improve documentation

Comments

@kwalrath
Copy link
Contributor

kwalrath commented Oct 2, 2013

Here are the dart:collection pages that are in the top 100 views on api.dartlang.org:

/dart_collection.html
/dart_collection/HashMap.html
/dart_collection/Maps.html
/dart_collection/LinkedList.html

@kwalrath
Copy link
Contributor Author

kwalrath commented Jun 4, 2014

Removed Type-Defect, Area-Documentation labels.
Added Type-Documentation, Area-Library labels.

@lrhn
Copy link
Member

lrhn commented Jun 5, 2014

We should continually improve all parts of the system, so this bug isn't really saying anything. Unless there are some concrete suggestions for improvement, this issue is impossible to close as fixed, and therefore not really useful.

@kwalrath
Copy link
Contributor Author

kwalrath commented Jun 5, 2014

The only thing useful about this bug is the list of actual pages to concentrate on (the library and 3 classes).

@kwalrath kwalrath added type-documentation A request to add or improve documentation Priority-Unassigned area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. library-collection labels Jun 5, 2014
@srawlins
Copy link
Member

srawlins commented Oct 9, 2015

The good:

The bad:

@lrhn
Copy link
Member

lrhn commented Oct 11, 2015

The Maps class really, really shouldn't exist. It's a left-over from before we had mixins. That said, it exists, so it should be documented (so we can recommend you use MapMixin instead!).

The LinkedList would also be a prime candidate for moving into a package if that ever becomes possible. It is significantly different from the remaining collections in core.
Again, it should still be documented. And maybe copied to package collection, so we can recommend people use that version, in a bid to - eventually - deprecate it.

@sethladd
Copy link
Contributor

@lrhn +1 for adding docs that say "you should be using this instead!" and perhaps even adding a @Deprecated('2.0') indicating that it's a candidate for removal in 2.0.

@srawlins
Copy link
Member

The Maps class has been deleted. LinkedList has great docs on the class, and doc comments on all class members.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-core-library SDK core library issues (core, async, ...); use area-vm or area-web for platform specific libraries. core-a library-collection type-documentation A request to add or improve documentation
Projects
None yet
Development

No branches or pull requests

5 participants