From 55eaed524e51ce27e12acf134bce855e34a00eaf Mon Sep 17 00:00:00 2001 From: Kavon Farvardin Date: Tue, 18 Nov 2025 14:36:17 -0800 Subject: [PATCH 1/2] Doc: add explainer for `Escapable` resolves rdar://146331729 --- stdlib/public/core/Misc.swift | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/stdlib/public/core/Misc.swift b/stdlib/public/core/Misc.swift index c3cbdec21b63c..2a7620e0a8fac 100644 --- a/stdlib/public/core/Misc.swift +++ b/stdlib/public/core/Misc.swift @@ -239,7 +239,20 @@ func _rethrowsViaClosure(_ fn: () throws -> ()) rethrows { /// Extensions to the `Copyable` protocol are not allowed. @_marker public protocol Copyable/*: ~Escapable*/ {} -@_documentation(visibility: internal) +/// A protocol representing types whose values can persist beyond the immediate local context. +/// +/// They may be freely assigned to global or static variables, returned from functions, or captured by escaping +/// closures, etc. All Swift types implicitly conform to this protocol by default, allowing them to be moved across +/// scopes freely because they lack any lifetime dependencies. +/// +/// In contrast, values of types that suppress their implicit conformance to `Escapable` (by writing `~Escapable`) +/// carry a lifetime dependency. These dependencies ensure the `~Escapable` value does not live longer than the value it +/// depends on. Explicit lifetime dependency annotations may be required when working with these types. +/// +/// In generic contexts, `~Escapable` works much in the same way as `~Copyable`. It allows functions and types to work +/// with values that may or may not be Escapable, and types can be conditionally Escapable based on their generic +/// arguments. A conformance requirement for Escapable is automatically inferred in extensions and for generic type +/// parameters, unless suppressed with `~Escapable`. @_marker public protocol Escapable/*: ~Copyable*/ {} @_marker public protocol BitwiseCopyable: ~Escapable { } From 7e9608cccc455cffdccbcb566d00bfe1aaf093fe Mon Sep 17 00:00:00 2001 From: Kavon Farvardin Date: Tue, 18 Nov 2025 15:14:38 -0800 Subject: [PATCH 2/2] Doc: small fixes for `Escapable` explainer Thanks to a review from @amartini51 Co-authored-by: Alex Martini --- stdlib/public/core/Misc.swift | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/stdlib/public/core/Misc.swift b/stdlib/public/core/Misc.swift index 2a7620e0a8fac..0b74d706ebe35 100644 --- a/stdlib/public/core/Misc.swift +++ b/stdlib/public/core/Misc.swift @@ -239,10 +239,10 @@ func _rethrowsViaClosure(_ fn: () throws -> ()) rethrows { /// Extensions to the `Copyable` protocol are not allowed. @_marker public protocol Copyable/*: ~Escapable*/ {} -/// A protocol representing types whose values can persist beyond the immediate local context. +/// A type whose values can persist beyond their immediate local scope. /// -/// They may be freely assigned to global or static variables, returned from functions, or captured by escaping -/// closures, etc. All Swift types implicitly conform to this protocol by default, allowing them to be moved across +/// Escapable values can be assigned to global or static variables, returned from functions, captured by escaping +/// closures, and so on. All Swift types implicitly conform to this protocol by default, allowing them to be moved across /// scopes freely because they lack any lifetime dependencies. /// /// In contrast, values of types that suppress their implicit conformance to `Escapable` (by writing `~Escapable`) @@ -250,8 +250,8 @@ func _rethrowsViaClosure(_ fn: () throws -> ()) rethrows { /// depends on. Explicit lifetime dependency annotations may be required when working with these types. /// /// In generic contexts, `~Escapable` works much in the same way as `~Copyable`. It allows functions and types to work -/// with values that may or may not be Escapable, and types can be conditionally Escapable based on their generic -/// arguments. A conformance requirement for Escapable is automatically inferred in extensions and for generic type +/// with values that may or may not be Escapable, and types can be conditionally `Escapable` based on their generic +/// arguments. A conformance requirement for `Escapable` is automatically inferred in extensions and for generic type /// parameters, unless suppressed with `~Escapable`. @_marker public protocol Escapable/*: ~Copyable*/ {}