[SE-0198] Introduced CustomPlaygroundDisplayConvertible and deprecated PlaygroundQuickLook/CustomPlaygroundQuickLookable #14690
Conversation
|
Getting this up now so I can do this: @swift-ci Please test |
|
@airspeedswift Would you mind reviewing this to make sure I'm not off-base with how I put this in and the wording of the deprecation warning? (Or, alternatively, suggest someone else who can review it instead?) |
| @@ -14,6 +14,7 @@ import Foundation | |||
| @_exported import AppKit | |||
|
|
|||
| extension NSCursor : _DefaultCustomPlaygroundQuickLookable { | |||
| @available(*, deprecated, message: "NSCursor._defaultCustomPlaygroundQuickLook will be removed in a future Swift version") | |||
There was a problem hiding this comment.
I think we should still allow using it in Swift 3 and Swift 4.1 without warning. Therefore the attribute should look like:
@available(swift, deprecated: 4.1, message: "...").
There was a problem hiding this comment.
This is intentional -- perhaps these diagnostics are worded too lightly, but we plan on deleting (or at least we're going to try to delete) PlaygroundQuickLook and CustomPlaygroundQuickLookable from the standard library in Swift 5 as they depend on some things which we don't want locked into the stable ABI. As a result, we want users of these legacy APIs to see a deprecation warning even in the compatibility mode(s) so that they're incentivized to switch to the new API ASAP. (I updated the doc comments for PlaygroundQuickLook and CustomPlaygroundQuickLookable to include the #ifs needed to keep using this in Swift 4.0 and Swift 3.2 and earlier while using the new API in Swift 3.3+/Swift 4.1+.)
stdlib/public/core/Mirror.swift
Outdated
| @@ -660,8 +660,22 @@ internal extension Mirror { | |||
|
|
|||
| //===--- QuickLooks -------------------------------------------------------===// | |||
|
|
|||
| /// The sum of types that can be used as a Quick Look representation. | |||
There was a problem hiding this comment.
Let's keep the old abstract here and in the next one—the @availability deprecation gives enough information to mark the symbol.
stdlib/public/core/Mirror.swift
Outdated
| /// #endif | ||
| /// ``` | ||
| /// | ||
| /// - seealso: `CustomPlaygroundDisplayConvertible` |
There was a problem hiding this comment.
Can you drop these seealso markers, too?
stdlib/public/core/Mirror.swift
Outdated
| /// present when compiling with Swift 4.0 or Swift 3.2 or earlier: | ||
| /// | ||
| /// ```swift | ||
| /// #if !(swift(>=4.1) || swift(>=3.3) && !swift(>=4.0)) |
There was a problem hiding this comment.
Our Markdown style for examples is to use indented code blocks, not fenced ones, unless we're writing non-Swift code. The code itself should be indented with 4 spaces.
| /// | ||
| /// If this type has value semantics, the instance returned should be | ||
| /// unaffected by subsequent mutations if possible. | ||
| var playgroundDescription: Any { get } |
There was a problem hiding this comment.
This block should only be indented two spaces.
This protocol is intended as a replacement for `CustomPlaygroundQuickLookable` and `PlaygroundQuickLook`. It allows a type to return a substitute instance for use during playground logging.
…ookable`. Deprecated the `PlaygroundQuickLook` enum and `CustomPlaygroundQuickLookable` protocol. These are being targeted for removal in Swift 5, so we want to unconditionally deprecate them now to encourage use of `CustomPlaygroundDisplayConvertible` instead. This commit includes deprecated the various `CustomPlaygroundQuickLookable` conformances across the standard library and overlay libraries.
…aygroundQuickLookable`. Since these are now deprecated (in preparation for removal in a future Swift release), the doc comments reflect that and provide suggestions for what to do instead (i.e. use `CustomPlaygroundDisplayConvertible`) and how to conditionalize usage of `PlaygroundQuickLook`/`CustomPlaygroundQuickLookable` so that source code remains compilable both by old versions which only have the old protocol and newer versions which have removed the old protocol.
cwakamo
force-pushed
the
introducing-CustomPlaygroundDisplayConvertible
branch
from
e9ba4ef to
b3d1a83
Compare
|
@swift-ci Please smoke test |
|
@natecook1000 I added back the old doc comments but left the deprecation notices as notes so that I could show how to properly conditionalize usage of |
Introduced the
CustomPlaygroundDisplayConvertibleprotocol and unconditionally deprecatedPlaygroundQuickLookandCustomPlaygroundQuickLookable(and all conformances to those protocols) as part of implementation of SE-0198.These are the Swift-side changes for <rdar://problem/32905293>.