Execution context

[backuitist]

I've integrated some of your comments ;)

[backuitist]

Look i've changed the link. But you might want to remove it as it points at http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ForkJoinPool.html ?

[axel22]

I don't think there is a license problem with pointing back to Oracle's Java documentation.

Please break these two sentences into two lines.

[axel22]

I'm having second thoughts about mentioning FJ pool here.
The current ExecutionContext.global implementation, even though it's unlikely to change,
should be mentioned at most in the ScalaDoc API.
Otherwise, our documentation is too flaky, and it becomes hard to maintain the crossreferences.

This doc should discuss only the high-level usage and meaning of execution contexts,
not the specific implementation.
It is also unclear if we should mention minThreads, numThreads and maxThreads configuration settings,
since they are not mentioned explicitly in the API docs.

[axel22]

I would suggest that you refactor this section, so that all mention of ForkJoinPool is put in a separate section,
entitled e.g. "Execution Contexts based on Fork/Join Pools".

[backuitist]

I disagree, references of ExecutionContext.global are all over that documentation. So you might be right in theory, but in practice people will be using (and abusing) the global EC. Documenting how this works and flagging potential issues isn't low-level details.

[backuitist]

I would suggest that you refactor this section, so that all mention of ForkJoinPool is put in a separate section,
entitled e.g. "Execution Contexts based on Fork/Join Pools".

That's actually what I did by wrapping FJP details into the The Global Execution Context section.

[SethTisue]

review by @viktorklang and @axel22?

[axel22]

We normally write the type ascription immediately after the identifier, without the space:

val inverseFuture: Future[Matrix] = ... 

[viktorklang]

I recommend making the example take the EC as an implicit parameter to foster a culture of getting the EC passed in rather than defining it locally.

[axel22]

Agree - the more idiomatic version below could be sufficient.

[axel22]

Thanks a lot for taking the effort to improve the documentation to this extent!
Please address my comments before we can merge this in.

[viktorklang]

I'd suggest:

is a placeholder object for a value that may not yet exist.

[SethTisue]

@backuitist interested in getting this across the finish line...?

[backuitist]

Sorry, that went off my radar.

[SethTisue]

@axel22@viktorklang lgty now?

[axel22]

I would fix that one last colon, but it looks good to me.

[SethTisue]

yay, across the finish line! thank you @backuitist for your great patience, thank you reviewers. (@viktorklang, it's of course not too late for further changes.)

[viktorklang]

@SethTisue :-)