Docs: More docs on cluster joining, and how to do it.

[ktoso]

Maybe we can polish up and add some more methods...?

join is, on purpose, not async, to not cause a pain by having to wait for joining.

But may be it should be, if this fire-and-forget is causing people confusion?

We have already await system.cluster.joined(), and await system.cluster.waitFor(node, .up) and other conveniences, but perhaps the not async join is confusing people?

[ktoso]

Making all join/leave etc async IMHO sucks since often you don't really care and it'd cause

Task { await ... }
Task { await ... }
Task { await ... }
Task { await ... }

walls of doom heh...

• I also don't like if we did join() async and join() since then in async context you are FORCED to await...
• Another ugly option is to join() and joinWait() but that also is ugly...
• the public func waitFor(_ nodes: some Collection<Cluster.Node>, _ status: Cluster.MemberStatus, within: Duration) async throws APIs do what Peter asked for here but they don't initiate a join

We have convenience "waiters" await system.cluster.joined or rather the renamed await system.cluster.up() but they also don't initiate.

Perhaps we just need more documentation here?