Modernize the package's style.

Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com

Committed: https://github.com/dart-lang/collection/commit/65cd283e6ea5bdfe3f64ce556a24797410a4cfd4

[Lasse Reichstein Nielsen, 2016-01-27 10:12:28]

I'm slightly concerned about deprecating the top-level libraries (I use them!).
Having only one top-level library seems like a waste of potential when a package
*can* have more.
There is still a "collection.dart" which exports everything.

Still, it's not been used consistently with new additions, so it might be for
the better. 

LGTM

https://codereview.chromium.org/1638163002/diff/1/lib/algorithms.dart
File lib/algorithms.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/algorithms.dart#newcode5
lib/algorithms.dart:5: @Deprecated("Import collection.dart instead.")
The argument to Deprecated isn't a message, it should be saying when the library
is removed (which will likely be version 2.0.0).

Put the message in a comment on the library declaration instead.

https://codereview.chromium.org/1638163002/diff/1/lib/src/canonicalized_map.dart
File lib/src/canonicalized_map.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/src/canonicalized_map.d...
lib/src/canonicalized_map.dart:11: /// This is useful for using case-insensitive
String keys, for example. It's more
Long line.
The /// comment style allows one less character per line, so you have a lot of
long lines below.
(There are advantages to /** */!)

https://codereview.chromium.org/1638163002/diff/1/lib/src/wrappers.dart
File lib/src/wrappers.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/src/wrappers.dart#newco...
lib/src/wrappers.dart:284: /// `Map`, or it can be extended to add extra
functionality on top of an existing
Long line.
More below.

[nweiz, 2016-01-27 23:38:42]

Code review changes

[nweiz, 2016-01-27 23:43:07]

> I'm slightly concerned about deprecating the top-level
> libraries (I use them!). Having only one top-level library
> seems like a waste of potential when a package
> *can* have more. There is still a "collection.dart" which
> exports everything.

It's not the style that packages have settled on. A few do use multiple
top-level packages, but only when they need different prefixes or to separate
out console- or browser-only code. show/hide can be used to control what names
are visible from an all-in-one library, but in practice users don't seem to care
much about limiting their public namespace anyway. Name conflicts just aren't
very common.

https://codereview.chromium.org/1638163002/diff/1/lib/algorithms.dart
File lib/algorithms.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/algorithms.dart#newcode5
lib/algorithms.dart:5: @Deprecated("Import collection.dart instead.")
On 2016/01/27 10:12:28, Lasse Reichstein Nielsen wrote:
> The argument to Deprecated isn't a message, it should be saying when the
library
> is removed (which will likely be version 2.0.0).
> 
> Put the message in a comment on the library declaration instead.

Done.

https://codereview.chromium.org/1638163002/diff/1/lib/src/canonicalized_map.dart
File lib/src/canonicalized_map.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/src/canonicalized_map.d...
lib/src/canonicalized_map.dart:11: /// This is useful for using case-insensitive
String keys, for example. It's more
On 2016/01/27 10:12:28, Lasse Reichstein Nielsen wrote:
> Long line.
> The /// comment style allows one less character per line, so you have a lot of
> long lines below.
> (There are advantages to /** */!)

Done.

https://codereview.chromium.org/1638163002/diff/1/lib/src/wrappers.dart
File lib/src/wrappers.dart (right):

https://codereview.chromium.org/1638163002/diff/1/lib/src/wrappers.dart#newco...
lib/src/wrappers.dart:284: /// `Map`, or it can be extended to add extra
functionality on top of an existing
On 2016/01/27 10:12:28, Lasse Reichstein Nielsen wrote:
> Long line.
> More below.

Done.

[nweiz, 2016-01-27 23:43:51]

Description was changed from

==========
Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com
==========

to

==========
Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com

Committed:
https://github.com/dart-lang/collection/commit/65cd283e6ea5bdfe3f64ce556a2479...
==========

[nweiz, 2016-01-27 23:43:52]

Committed patchset #2 (id:20001) manually as
65cd283e6ea5bdfe3f64ce556a24797410a4cfd4 (presubmit successful).