People often complain online that Swift has too many keywords. Whether or not that's fair, I think some of those keywords get in the way of progressive disclosure in documentation.
Consider Task
initializer:
@discardableResult
init(
priority: TaskPriority? = nil,
operation: sending @escaping @isolated(any) () async -> Success
)
While each keyword has a meaning and serves its purpose, this kind of highly technical function signature, though accurate, obscures the primary intent.
That’s scary and overwhelming for someone who just started learning SwiftUI and wants to call an async
function to make a network request inside a SwiftUI Button
action.
What if DocC had a simplified mode (enabled by default and optionally disabled), so that only essential information is displayed?
The simplified version of the above could be:
init(
priority: TaskPriority? = nil,
operation: () async -> Success
)
This preserves the core purpose while omitting details that are not essential for most readers.
This simplified mode would offer progressive disclosure in documentation. When—and if—you reach the point where it matters to know that operation
is a closure that is sending @escaping @isolated(any)
, you can refer to the full documentation.
Another example is the map
function:
func map<T, E>(_ transform: (Self.Element) throws(E) -> T) throws(E) -> [T] where E : Error
For someone who just wants to map [Person]
to [String]
, a simplified version would be enough:
func map<T>(_ transform: (Self.Element) -> T)
With this signature, you don’t have to immediately learn about errors or even Self
.
With this signature, you don’t have to immediately learn about errors.
As an educator, I try to show students the official documentation as much as possible, but often I have to ask them to abstract away or ignore certain parts. It’s still really hard for them not to get distracted. It’s probably even harder for a self-learner who just reached the documentation on their own.
I believe this kind of simplification could make Swift documentation more approachable and friendly for newcomers.