Added examples to map.dart

sdk/lib/core/map.dart

Index: sdk/lib/core/map.dart
diff --git a/sdk/lib/core/map.dart b/sdk/lib/core/map.dart
index fd3fd01560a67956f5ca7591dc2e2d318d6c01ea..9c9f1fedd048cc2424045a7dc4ad7b3d82f16c3a 100644
--- a/sdk/lib/core/map.dart
+++ b/sdk/lib/core/map.dart
@@ -5,8 +5,8 @@
 part of dart.core;
 
 /**
- * An unordered collection of key-value pairs,
- * from which you retrieve a value by using its associated key.
+ * An unordered collection of key-value pairs, from which you retrieve a value
+ * by using its associated key.

[Lasse Reichstein Nielsen, 2013/09/24 08:29:08]

Do we want a single-line summary for classes as well as for methods.

We generally try to start method descriptions with a single one-line summary. I
believe that at some point there was a summary view in the DartDoc that shows
only the first line/sentence/something, but I can't find it now. Maybe it's no
longer relevant?

[Kathy Walrath, 2013/09/25 18:11:09]

Yes, everything needs a single-line summary.
It's in the new dartdoc. You can see it here:

http://css-inprogress.dart-documentation.appspot.com/#dart-core#id_Map
http://css-inprogress.dart-documentation.appspot.com/#dart-core/Map

(It's still a work in progress. Alan's converting it to Polymer, and an external
designer is working on the look.)

  *
  * Each key can occur at most once in a map.
  */
@@ -22,18 +22,36 @@ abstract class Map<K, V> {
   factory Map.from(Map<K, V> other) = LinkedHashMap<K, V>.from;
 
   /**
-   * Creates a Map instance
-   * where the keys and values are computed from the [iterable].
+   * Creates a Map instance in which the keys and values are computed from the
+   * [iterable].
    *
    * For each element of the [iterable] this constructor computes a key-value
    * pair, by applying [key] and [value] respectively.
    *
-   * The keys computed by the source [iterable]
-   * do not need to be unique. The last
-   * occurrence of a key will simply overwrite any previous value.
+   * The example below creates a new Map from a List. The keys of `map` are
+   * `list` values converted to strings, and the values of the `map` are the
+   * squares of the `list` values:
+   *
+   *     List<int> list = [1, 2, 3];
+   *     Map<String, int> map = new Map.fromIterable(list,
+   *         key: (item) => item.toString(),
+   *         value: (item) => item * item));
+   *
+   *     map['1'] + map['2']; // 1 + 4
+   *     map['3'] - map['2']; // 9 - 4
    *
    * If no values are specified for [key] and [value] the default is the

[floitsch, 2013/09/23 12:16:07]

or [value]

    * identity function.
+   *
+   * In the following example, the keys and corresponding values of `map`
+   * are `list` values:
+   *
+   *     map = new Map.fromIterable(list);

[floitsch, 2013/09/23 12:16:07]

Maybe:
Since this is not really a useful example: only provide one of the arguments?

map = new Map.fromIterable(list, value: (item) => "$item");
map[1];  // "1"

...

[shailentuli, 2013/09/27 14:27:49]

The point of the example is to show what happens if you provide no arguments.

+   *     map[1] + map[2]; // 1 + 2
+   *     map[3] - map[2]; // 3 - 2
+   *
+   * The keys computed by the source [iterable] do not need to be unique. The
+   * last occurrence of a key will simply overwrite any previous value.
    */
   factory Map.fromIterable(Iterable iterable,
       {K key(element), V value(element)}) = LinkedHashMap<K, V>.fromIterable;
@@ -44,6 +62,11 @@ abstract class Map<K, V> {
    * This constructor iterates over [keys] and [values] and maps each element of
    * [keys] to the corresponding element of [values].
    *
+   *     List<String> letters = ['b', 'c'];
+   *     List<String> words = ['bad', 'cat'];
+   *     Map<String, String> map = new Map.fromIterables(letters, words);
+   *     map['b'] == 'bad' && map['c'] == 'cat';  // true

[floitsch, 2013/09/23 12:16:07]

I would prefer:
map['b'];  // 'bad'
map['c'];  // 'cat'

[shailentuli, 2013/09/27 14:27:49]

I've changed this. I generally try to avoid extremely short expressions. So, for
example, the following does not look that good to me:

List<int> list = [...];
list.sort();
list;  // [...]

It is better to make the last line something like this (as long as it doesn't
obscure the example):

list.join(', '); // ...

+   *
    * If [keys] contains the same object multiple times, the last occurrence
    * overwrites the previous value.
    *
@@ -80,8 +103,16 @@ abstract class Map<K, V> {
    * updates the map by mapping [key] to the value returned by
    * [ifAbsent]. Returns the value in the map.
    *
-   * It is an error to add or remove keys from the map during the call to
-   * [ifAbsent].
+   *     Map<String, int> scores = {'Bob': 36};
+   *     for (var key in ['Bob', 'Rohan', 'Sophena']) {
+   *       scores.putIfAbsent(key, () => 25);

[floitsch, 2013/09/23 12:16:07]

Maybe put an example that allocates something (or has a side-effect)?
To show why this is a function and not just a value.

[shailentuli, 2013/09/27 14:27:49]

Done.

+   *     }
+   *     scores['Bob'];      // 36
+   *     scores['Rohan'];    // 25
+   *     scores['Sophena'];  // 25
+   *
+   * An error occurs if you try to add or remove keys from the map during the

[floitsch, 2013/09/23 12:16:07]

We generally write "it is an error". Why do you prefer this wording?

[Lasse Reichstein Nielsen, 2013/09/24 08:29:08]

I agree with Florian.
We write "It is an error" but omit writing what happens if you do it anyway, so
that we have some leeway in implementing it. It will *usually* lead to an Error
object being thrown, but in unchecked mode the user may sneak in objects that
behave in such a way that it completes (with a result you can't trust,
ofcourse).

This example is a "concurrent modification" error. These are generally
"best-effort", and can be cheated by clever users (something like doing 2^32
add/remove operations may make our modification counter wrap and the
modification go undetected) - if we specified that it must throw an error, we
couldn't even allow this.

[Kathy Walrath, 2013/09/25 18:11:09]

I talked with Florian about this on another thread. We try to avoid "It is"
because that's a weak way to open a sentence (no content at all, it's anathema
to tech writers). Also, "It is an error" makes me think that an error will be
thrown, and that's not true. Other ways we could put it would be:

Don't add or remove keys in [ifAbsent].

OR

The code that [ifAbsent] executes must not add or remove keys.

[shailentuli, 2013/09/27 14:27:49]

I'm using Kathy's version, but I'm not deeply attached to any particular
wording.

+   * call to [ifAbsent].
    */
   V putIfAbsent(K key, V ifAbsent());