Document `$` and Binding

[mleonhard]

Is your feature request related to a problem? Please describe. I need to understand how SwiftUI variable bindings work.

Describe the solution you'd like Searching for site:docs.swift.org "binding" should return a page that describes the $ symbol https://duckduckgo.com/?q=site%3Adocs.swift.org+"binding"

Describe alternatives you've considered I searched a lot and finally found some info at developer.apple.com > Documentation > SwiftUI > State and Data Flow > Binding .

Additional context

[0xTim]

Binding is a SwiftUI concept and not a Swift language concept isn't it? Since SwiftUI is Apple only, it doesn't make sense to have the information on the language documentation

[stevapple]

The $ prefix represents the general concept of "projected value" with property wrappers in Swift, which is documented in https://docs.swift.org/swift-book/LanguageGuide/Properties.html#ID619

Binding is a property wrapper defined by SwiftUI, which is not a part of Swift itself.

[mleonhard]

Thanks for the link to the docs page. That docs page could mention that "binding" is a SwiftUI term and link to the corresponding SwiftUI docs. This would make the docs page more findable with search. That could save a lot of new Swift users from wasting effort and feeling frustration.

[0xTim]

That docs page could mention that "binding" is a SwiftUI term

I disagree with this. This opens a can of worms so it's easiest to draw a line and stick to swift.org documentation only contains documentation on the Swift language. SwiftUI is popular so there could be justification in adding something about binding in the Swift docs but a) SwiftUI is a private framework not under the Swift umbrella. The SwiftUI (like all other iOS/macOS etc) documentation should live on developer.apple.com. And b) where do you draw the line. Vapor's Fluent uses property wrappers extensively, should Swift.org also talk about that and link to the Vapor docs. What about etc

My 2₵

[stevapple]

That could save a lot of new Swift users from wasting effort and feeling frustration.

Swift users are not necessarily SwiftUI users, and SwiftUI is not a Swift open source project at this time. There’s no reason to refer to any 3rd party framework in the official document, no matter how popular it is (still doubt if SwiftUI is the top popular Swift framework).

For any Swift framework, you should look for its own documentation, usually hosted by its developer or vendor. The official Swift documentation should only cover the language itself and the standard libraries — even core libraries are not included yet.

[mleonhard]

There’s no reason to refer to any 3rd party framework in the official document, no matter how popular it is (still doubt if SwiftUI is the top popular Swift framework).

There is a reason: To help users. That's the purpose of documentation. Siloed documentation is hard to use, especially for beginners. Beginners often don't understand the line between the "Foundation" and "SwiftUI". This line is hard to learn by reading code because examples usually import all of the symbols in these libraries. So you never see something like import SwiftUI::{Binding, Button, View}. I'm not sure if the language even supports such unambiguous and educational import statements.

Software structure reflects the structure of the organizations that produce it. Software dependencies are DAGs. Documentation is not. Documentation link cycles are good and useful. The best documentation contains lots of links to things people need to know, no matter the organizational lines crossed. A sentence and a link has low maintenance cost and can save many users 10-20 minutes each. This is a massive return for small effort.

Please focus on your users!

Are you interested in helping only people who use Swift stand-alone, not with SwiftUI or Vapor?

Do you want more and more people to use Swift? Make the documentation meet their needs!

[kaishin]

Do you want more and more people to use Swift? Make the documentation meet their needs!

In general, this is a good principle to follow.

In this case, however, it presents the risk of making a user who's already confused about what is what, even more confused about what is what, due to the lack of a clear distinction about language features and framework features. Someone might attempt to use a binding without importing SwiftUI for instance.

Making a guide in the SwiftUI documentation about specific Swift features that empower it might be a good idea however.

[mleonhard]

You can prevent confusion by including the necessary information. Example:

When writing code that uses SwiftUI library, use $ on a State<T> variable to get a binding that allows changing the inner T value. This works because State<T>.projectedValue returns Binding<T>.

[0xTim]

I'm going to close this for now. The newly announced documentation group can pick this up if they want.

As mentioned above, the problem with the suggestion is that that opens a can of worms as it ends up like:

When writing code that uses SwiftUI library, use $ on a State variable to get a binding that allows changing the inner T value. This works because State.projectedValue returns Binding. When writing code that uses Fluent, use $ on a FieldKey to get the underlying property wrapper for the field. When writing code that uses Random library X .... When writing code that uses Random library Y...

So we'll leave it as is for now

[mleonhard]

@0xTim @alexandersandberg @kaishin @stevapple I think that refusing to add useful documentation is a user-hostile action. :( Isn't Apple's culture about focusing on the user? Developers are your users. That user-focus must extend to developers who build the apps that make Apple's products useful and make Apple so much money ($64B App Store revenue in 2020).

Writing apps is TOO HARD. Few individuals can do it and instead we need teams. Teams are very hard to start without venture capital. So most of our apps are built with VC money. This hurts human society in many ways:

1. VCs force their companies to do immoral things like making their software addictive (actively harming their users), manipulating their users, tracking users and storing their behavior data forever, and selling user data.
2. Society misses out on the many kinds of apps that cannot get VC funding.

You all have responsibility as educated humans to help human society flourish. Part of that is to reduce friction in foundational technologies like Swift & iOS. Please reconsider your stance on documentation for your project and reconsider your decision to omit information about Swift's $ operator and iOS's Binding class.

[mleonhard]

cc @TimTr (Developer experience at Apple)