Add one-line description to dart:isolate, plus a start at doc comment cleanup.

Add one-line description to dart:isolate, plus a start at doc comment cleanup.

R=sethladd@google.com

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

[Kathy Walrath, 2013-08-21 13:15:05]

Please take a look, Seth. I've confirmed that this generates reasonable doc in
the new viewer.

[sethladd, 2013-08-21 17:23:17]

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
File sdk/lib/isolate/isolate.dart (right):

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
sdk/lib/isolate/isolate.dart:7: * threads of execution that communicate via
messages.
threads are an overloaded term. can we find a better term?

[Kathy Walrath, 2013-08-21 17:44:24]

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
File sdk/lib/isolate/isolate.dart (right):

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
sdk/lib/isolate/isolate.dart:7: * threads of execution that communicate via
messages.
On 2013/08/21 17:23:18, sethladd wrote:
> threads are an overloaded term. can we find a better term?

The reason that I included it is because some people might search for "thread"
in the page. We could do instead:

1. independent threads of execution that...
2. independent, thread-like units of execution that...
3. thread-like units of execution that...

I'm not crazy about any of those, but #1 seems better because it doesn't assume
knowledge of threads.

Another term people might know that we could use might be "worker". Maybe:

4. independent workers that are similar to threads of execution but don't share
memory,
communicating only via messages.

Which one do you prefer? Can you think of something better?

[sethladd, 2013-08-21 19:16:42]

lgtm

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
File sdk/lib/isolate/isolate.dart (right):

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
sdk/lib/isolate/isolate.dart:7: * threads of execution that communicate via
messages.
"Concurrent code that communicates via message passing."

?

[sethladd, 2013-08-21 19:17:02]

oops, didn't mean lgtm

[Kathy Walrath, 2013-08-21 21:23:10]

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
File sdk/lib/isolate/isolate.dart (right):

https://chromiumcodereview.appspot.com/22871017/diff/1/sdk/lib/isolate/isolat...
sdk/lib/isolate/isolate.dart:7: * threads of execution that communicate via
messages.
On 2013/08/21 19:16:42, sethladd wrote:
> "Concurrent code that communicates via message passing."
> 
> ?

No mention of "worker" or "thread"?

[sethladd, 2013-08-21 22:01:39]

I'm just worried that thread and worker (in the HTML5 world) are overloaded and
come with expectations. I was hoping concurrent would be sufficient.

I'll trust your judgement.

[Kathy Walrath, 2013-08-21 23:06:05]

How about this?

I know worker and thread are overloaded, but I think people will look for those
terms. Cutch was good with this wording, fwiw.

[Kathy Walrath, 2013-08-22 00:38:44]

Committed patchset #2 manually as r26498 (presubmit successful).