Update Task.cancel() with more details

[ktoso]

Add more details into cancel() docs, some developers were worried if they are allowed to call it concurrently and multiple times etc.

[smumriak]

Thank you!

[ktoso]

@swift-ci please smoke test

[FranzBusch]

Maybe it's worth adding that any taskCancellationHandler that's setup is run once task.cancel() is called from the thread that calls it

[ktoso]

I'm not sure we want to document the threading guarantee hmmm... I did include that a note that cancellation handlers run just once though, good enough?

[amartini51]

Fixed spelling of "canceled" per APSG and left a suggested rewording.

[rjmccall]

Suggestion:

Cancels this task.

Cancelling a task has three primary effects:

• It flags the task as cancelled.
• It causes any active cancellation handlers on the task to run.
• It cancels any child tasks and task groups of the task, including
  those created in the future.

Task cancellation is cooperative in the sense that cancelling a
task does not automatically cause arbitrary functions on the task
to stop running or throw errors. A function may choose to react
to cancellation by ending its work early, and it is conventional to
signal that to callers by throwing CancellationError. However,
a function that doesn't specifically check for cancellation will
run to completion normally even if the task it is running on is
cancelled. (Of course, it may still end early if it calls something
else that handles cancellation by throwing and then doesn't
handle the error.)

It is safe to cancel a task from any task or thread. It is safe for
multiple tasks or threads to cancel the same task at the same
time. Cancelling a task that has already been cancelled has no
additional effect.

cancel may need to acquire locks and synchronously run
arbitrary cancellation-handler code associated with the
cancelled task. To reduce the risk of deadlock, it is
recommended that callers release any locks they might be
holding before they call cancel.

• SeeAlso: Task.checkCancellation()
• SeeAlso: withTaskCancellationHandler()

[ktoso]

That's pretty comprehensive, lemme take that -- thanks @rjmccall

[ktoso]

@swift-ci please smoke test

[rjmccall]

@amartini51 Please do a style check for the revised wording — we effectively have a sort of "merge conflict" here.

[amartini51]

@rjmccall Thanks — opened #76560 with minor documentation style fixes.