SwiftUI Documentation for @State property wrapper

Question

I recently ran into an issue where I had to init an @State variable in my init method. This post helped me figure that out.

What I realized was that this is the way to do it:

@State var fullText: String // No default value of ""

init(letter: String) {
    _fullText = State(initialValue: list[letter]!)
}

I understand that @State is a property wrapper, and I read the documentation on property wrappers. And from other reading I discovered under the hood this code:

@State private var flag = false

is translated into this code:

private var _flag: State<Bool> = State(initialValue: false)
private var $flag: Binding<Bool> { return _flag.projectedValue }
private var flag: Bool {
    get { return _flag.wrappedValue }
    nonmutating set { _flag.wrappedValue = newValue }
}

My question is where is it documented that _variableName is created from the wrapped property method and I can redefine it? How is a SwiftUI developer supposed to know that from Apple's docs? I'm trying to find what I'm assuming is Documentation I'm missing.

Answer 1

As property wrappers were a Swift Evolution proposal and were developed as part of Swift's open source philosophy, we can find the best documentation directly in the Proposal SE-0258 document. This describes the rationale behind the @propertyWrapper design, and the exact specification to how they are implemented (including the definitions of wrapped values and projected values).

Sections that may help in your understanding:

§ A property wrapper type provides the storage for a property that uses it as a wrapper. The wrappedValue property of the wrapper type provides the actual implementation of the wrapper, while the (optional) init(wrappedValue:) enables initialization of the storage from a value of the property's type.

The use of the prefix _ for the synthesized storage property name is deliberate: it provides a predictable name for the synthesized storage property that fits established conventions for private stored properties.

[...]

§ A property wrapper type can choose to provide a projection property (e.g., $foo) to expose more API for each wrapped property by defining a projectedValue property. As with the wrappedValue property and init(wrappedValue:), the projectedValue property must have the same access level as its property wrapper type.

As property wrappers are new to Swift as a whole, documentation is still lacking on Apple's side in my opinion, especially when it comes to SwiftUI. However, there are only a handful of property wrappers we really have to know about (@State, @Binding, @EnvironmentObject, @ObservedObject, @Published) to fully utilise SwiftUI; all other aspects of SwiftUI (such as View types) are pretty well documented in Apple's Developer docs.

Additionally, articles shared in the Swift community (example) can help you to get a grasp on where you might want to implement property wrappers yourself!