Expanding `available`

Proposal: SE-nnnnnnnn
Authors: Chris Lattner, Erica Sadun
Review Manager: TBD
Status: Awaiting implementation

Introduction

Swift's available attribute documents characteristics of a declaration's lifecycle. It specifies when a declaration became available on a given platform, if it's been deprecated, obsoleted, or renamed. We feel there's room to further nuance available. This proposal expands the attribute to introduce the notions of discouragement (making declarations harder to use) and supersedence (replacing a declaration with a preferred version).

Swift-evolution thread: Discussion thread topic for that proposal // FIXME:

Motivation

Discouragement steers adopters away from certain APIs. When a declaration is visible but should not be used, discouragement enables the coding environment to actively work with the coder to avoid those calls.

Supersedence occurs when new declarations are introduced without deprecating or obsoleting the original form they are based on. This approach allows library developers to prefer a newer declaration and discourage an existing one without breaking existing code. Supersedence "soft deprecates" an existing name or declaration.

Discouragement

At times, developers want to discourage API use. For example, initializer requirements in the LiteralConvertible protocols are redundant with the primary protocols. They are meant to be implemented, but not called. Marking them discouraged documents this reality and helps the development environment hide them from cues like code completion.

When declarations are visible but should not be used, discouraging their use provides tangible benefit to coders:

It increases coding safety.
It supports clarity, as the current uses of available, do by offering availability status information co-located with code documentation.
It offers a way to connect a declaration with development environment policy. A discouraged declaration may be warned or hidden from code completion depending on the implementation provided in an IDE.

Supersedence

On the path to deprecation, breaking changes have a necessarily high bar, whether in third party libraries, the Swift project, or related projects. A slow and cautious approach supports reconsidering and refactoring APIs with less turbulence.

Developers may want to slow-walk deprecation to minimize trauma and provide the best experience for consumers who are used to and depend upon existing calls. Reasons for updating the declaration vary. The developer may want to remedy an imperfectly designed API surface, to reconsider prior decisions, or to modernize calls.

Supporting co-existing declarations without deprecation and choosing which ones to discourage is not currently addressed in the Swift programming language. Developers should be able to offer parallel signatures and functionality for a period of time before, if ever, easing out the older declarations into deprecation.

Proposed solution

This proposal extends available to introduce discouragement and supersedence. A discouraged declaration is publicly accessible but not meant for general use. A superseded declaration continues to work and, depending on the whether its use is also discouraged, may produce a range of outcomes from peaceful coexistence to warnings or deliberate interference in code completion. A declaration can be both discouraged and superseded, or just one, or neither.

Detailed design

The available attribute currently supports the following arguments:

Argument	Description
`introduced`	The first platform or language version that supported the declaration.
`renamed`	A name that entirely replaces the old declaration, emitting a compile-time error.
`message`	A message to display when emitting a warning or error for deprecated and obsoleted declarations.
`deprecated`	The first platform or language version where the declaration was deprecated.
`obsoleted`	The first platform or language version where the declaration was removed and can no longer be used.
`unavailable`	Indicates a declaration is not available for a given platform.

Our proposed design expands available to introduce the notion of declaration supersedence, and the policies that support the parallel existence of two functionally identical declarations.

Argument	Description
`discouraged`	A message to display that describes why this declaration is discouraged
`superseded`	The first platform or language version where the declaration was superseded and a replacement declaration introduced.
`superseded_by`	The declaration signature that takes the place of this declaration.
`supersedes`	The declaration signature this declaration replaces

IDE integration

Discouraged declarations can be picked up by the IDE experience in several ways:

They could be suppressed from code completion or only show up in code completion once they are the only unambiguous option.
They could given a strikethrough treatment.

Further, each of the new arguments can be picked up and displayed in Quick Help.

Source compatibility

This change is purely additive and will not affect source compatibility.

Effect on ABI stability

<TBD> // FIXME:

Effect on API resilience