Added examples to map.dart

sdk/lib/core/map.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 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.
  */
 abstract class Map<K, V> {
   /**
    * Creates a Map instance with the default implementation.
    */
   factory Map() = LinkedHashMap<K, V>;
 
   /**
    * Creates a Map instance that contains all key-value pairs of [other].
    */
   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;
 
   /**
    * Creates a Map instance associating the given [keys] to [values].
    *
    * 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.
    *
    * It is an error if the two [Iterable]s don't have the same length.
    */
   factory Map.fromIterables(Iterable<K> keys, Iterable<V> values)
       = LinkedHashMap<K, V>.fromIterables;
 
   /**
    * Returns true if this map contains the given value.
@@ skipping 16 matching lines @@
   /**
    * Associates the [key] with the given [value].
    */
   void operator []=(K key, V value);
 
   /**
    * If [key] is not associated to a value, calls [ifAbsent] and
    * 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());
 
   /**
    * Adds all key-value pairs of [other] to this map.
    *
    * If a key of [other] is already in this map, its value is overwritten.
    *
    * The operation is equivalent to doing `this[key] = value` for each key
    * and associated value in other. It iterates over [other], which must
@@ skipping 39 matching lines @@
   /**
    * Returns true if there is no {key, value} pair in the map.
    */
   bool get isEmpty;
 
   /**
    * Returns true if there is at least one {key, value} pair in the map.
    */
   bool get isNotEmpty;
 }