However, if you read the proposal text while paying a little bit of attention, it says "see example:" right before the code snippet. Moreover, it does work in practice today:
$ echo 'print(1 + 2 & 3)' | xcrun swift
3
Given that, it seems kinda' an odd choice of an example... Should we tweak such examples to not contradict what happens in practice? I feel that part of the point of examples is motivating why a change is needed, but if the actual behavior is opposite to what is/was written in the example, that seems kinda' contradictory.
But that's not the example at all; you're quoting the last line of a 16-line code example. The example involves defining a bunch of operator precedences and operators, and then, given those hypothetical definitions, using them to demonstrate the behavior that would occur. The document is correct as-is.
Not only that, but at the time the proposal was written, both those definitions and the ones available today were equally hypothetical as nothing was implemented. The behavior we have today exists only because the document outlined it, and the document successfully outlined the intended behavior only by building its explanation step by step with the examples it provided. Nothing is contradicted.
However, if you read the proposal text while paying a little bit of attention, it says "see example:"
So I understand that it is hypothetical example, not reflective of real code. Nowhere have I stated that the document is incorrect.
If you have a better word than contradiction, I'm all ears. I concede that maybe I shouldn't have used the word "contradict". But my overall point still stands. Examples have at least two roles: (1) explanatory and (2) motivational. From an explanatory point-of-view, there is no issue, it makes sense. From a motivation point-of-view, it seems like a better example could have been chosen because it seems to be advocating for something (namely, that is desirable to have the precedence of addition and bitwise-and be unordered) that is not actually the case in practice.
Now, you could argue that the role of this example is purely explanatory and not motivational, because it's in the Proposed Solution section and not in the Motivation section. If that's the argument you're making, I find that somewhat reasonable, but it still begs the question: why not choose a better example that doesn't have this kind of issue?
Thatās great feedback for a proposal draft, or perhaps even in review. For this proposal, the Swift Evolution process is concluded, and the document accurately captures the motivation and the designed solution as accepted into Swift at that time. There is no provision for a āgit rebaseā-like process to rewrite accepted proposals to include new motivation retroactively.
I'm not familiar with this proposal, but I do find it extremely confusing when reading an accepted proposal, or even an accepted with modifications proposal and the actual feature behaves differently. Often there is very little official documentation. I understand that writing official documentation is very hard, but proposals can be written in a way that is both more informal and more technical, so it should be a simpler task.
I'd go so far as to say we shouldn't even accept proposals until they match the implementation!