Fix various documentation issues.

Fix various documentation issues.

Update Future documentation.
Update Future.then to not mention `f`.
Update documentation of toEncodable in dart:convert JSON conversion.
Fix typo in Map documentation.

BUG= http://dartbug.com/17424
BUG= http://dartbug.com/17395
BUG= http://dartbug.com/17089
BUG= http://dartbug.com/16820
R=ajohnsen@google.com

Committed: https://code.google.com/p/dart/source/detail?r=33652

[Lasse Reichstein Nielsen, 2014-03-12 08:07:10]

+sgjesse while ajohnsen is out of the office.

[Anders Johnsen, 2014-03-12 09:21:01]

lgtm

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:45: * This special case makes sure that no error is
silently dropped.
Behavior?

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:52: *       // The error-handler is only attached 5 ms
after the future has been
Is first attached?

Or

Is not attached until 5 ms after....

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:60: * In general we encourage registering the two
callbacks separately,
IMO "we" should not be used in code docs.

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:64: * and the value-handler for [catchError]), are
automatically
Value handler for catch error - do we have that?

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/convert/json.dart
File sdk/lib/convert/json.dart (right):

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/convert/json.dar...
sdk/lib/convert/json.dart:89: * need not be directly encodable, and if they
aren't, `toEncodable` will
Does not need ...

[Lasse Reichstein Nielsen, 2014-03-13 15:11:55]

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:45: * This special case makes sure that no error is
silently dropped.
On 2014/03/12 09:21:01, Anders Johnsen wrote:
> Behavior?

Done.

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:52: *       // The error-handler is only attached 5 ms
after the future has been
On 2014/03/12 09:21:01, Anders Johnsen wrote:
> Is first attached?
> 
> Or
> 
> Is not attached until 5 ms after....

Done.

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:60: * In general we encourage registering the two
callbacks separately,
On 2014/03/12 09:21:01, Anders Johnsen wrote:
> IMO "we" should not be used in code docs.

Done.

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/async/future.dar...
sdk/lib/async/future.dart:64: * and the value-handler for [catchError]), are
automatically
No, which is why it's missing (and why "missing" is better than "omitted"
anyway). Reworded.

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/convert/json.dart
File sdk/lib/convert/json.dart (right):

https://codereview.chromium.org/195203002/diff/20001/sdk/lib/convert/json.dar...
sdk/lib/convert/json.dart:89: * need not be directly encodable, and if they
aren't, `toEncodable` will
On 2014/03/12 09:21:01, Anders Johnsen wrote:
> Does not need ...

Done.

[Lasse Reichstein Nielsen, 2014-03-13 15:13:32]

Committed patchset #3 manually as r33652 (presubmit successful).

[Søren Gjesse, 2014-03-14 08:10:14]

lgtm, with comment

https://codereview.chromium.org/195203002/diff/40001/sdk/lib/convert/json.dart
File sdk/lib/convert/json.dart (right):

https://codereview.chromium.org/195203002/diff/40001/sdk/lib/convert/json.dar...
sdk/lib/convert/json.dart:85: * values that are not directly encodable to a
JSON1toE
What is "a JSON1toE string"?