Mark GlobalScope as delicate API and rewrite coroutine basics doc without it

[elizarov]

Also, remove the tutorial variant of the basic coroutine introduction as it essentially duplicates the content of the
basic coroutine introduction, albeit with "how to create a project" additional information, which does not seem to be appropriate in this section at all.

Fixes #2122

[qwwdfsad]

Please update api dump

[mhernand40]

Excited to see this! Thank you.

Curious what the fate is for some of the reactive stream interop APIs such as rxSingle, rxMaybe, rxCompletable, etc. which internally leverage GlobalScope in order to break out of structured concurrency? Will these APIs be marked as delicate as well?

[elizarov]

@mhernand40

Excited to see this! Thank you.

Curious what the fate is for some of the reactive stream interop APIs such as rxSingle, rxMaybe, rxCompletable, etc. which internally leverage GlobalScope in order to break out of structured concurrency? Will these APIs be marked as delicate as well?

They don't really break out of structured concurrency, they encapsulated into the well-known world of cancellation in Rx. Supposedly, if you use them you are aware of the Rx-style approach to handling it.

The story is different with GlobalScope, since coroutines are structured by default, so bits of API that are not structured and require special attention need to be marked.

[qwwdfsad]

Awesome guide re-write, well done!

Few minor comments and it's good to go

[qwwdfsad]

Also, please don't forget to add opt-in to our Gradle scripts, because now all the rx integrations is highlighted with warning

[koshachy]

Some minor improvements.
I hope that soon we will be able to bring all the documentation to our guidelines.

[mhernand40]

Also, please don't forget to add opt-in to our Gradle scripts, because now all the rx integrations is highlighted with warning

@elizarov, @qwwdfsad I guess this is what I was alluding to with my comment above. 🙂

[elizarov]

Fixed review commend, also:

• Added a formal definition on "what is a coroutine" to the basic docs (simplified version from the KEEP)
• Added more documentation on the intended usage of CoroutineScope() function CoroutineScope in its docs, as well as mentioned it in GlobalScope docs.

[qwwdfsad]

Good job!

[whyoleg]

@elizarov may be NonCancellable also a good candidate for DelicateCoroutinesApi ?
reference to #1001 (comment). Until some other solution come in place?

[elizarov]

IMO, NonCancellable is a different story. See GlobalScope is easy to abuse. People use it all the time when they should not be using it at all. I don't see this being a case with NonCancellable as much. Also, for NonCancellable we have a sketch of a different plan with an alternative.

[zach-klippenstein]

This is awesome, thank you so much!