Skip to content

Commit e1190a4

Browse files
committed
Clean up doc comments for task APIs.
Use only plain English words in abstracts, no symbol names, per reference writing guidelines. Use title case for headings. Use spelling from Apple Style Guide for 'canceled' and 'canceling'. Track TaskGroup async(...) renaming to addTask(...) in code examples. Fill in the -Parameters: markup for methods and initializers that take parameters, starting the sentence with an upper-case letter. Add links to TSPL for conceptual discussion, re-using the prose from elsewhere in the standard library reference for the cross reference. Restore some prose from fe288c2 in places where cleanup and revision work to doc comments got overwritten by API revision. Restore some prose that was in the discussion of Task.Handle that was deleted in commit 27bf2c9. Reduce the number of places where we talk about cooperative cancellation in detail, and let the individual properties and methods lean on the longer discussion in the overview for Task. Remove mention of error propagation from getResult(), which doesn't throw and therefor can't propagate errors thrown by a task. Remove mention of what the add(...) methods do if the operation throws an error from the non-throwing TaskGroup type, since the operation there can't ever be throwing. Remove -Returns: markup from properties and from methods that don't return a value. Stored and computed properties *have* a value, which is documented by their abstract and discussion sections; functions and methods *return* a value. Remove cross references when they refer to type that's part of the declaration. The rendered documentation already provides an affordance to navigate to a type in that context. Fixes <rdar://81184794>.
1 parent 5c1a527 commit e1190a4

File tree

4 files changed

+318
-285
lines changed

4 files changed

+318
-285
lines changed

0 commit comments

Comments
 (0)