Re-write text to propose likely/unlikely instead of expect

It's clear that `likely`/`unlikely` is the more popular option, so make
that the main focus.

Also expands on the guarantees the intrinsics provide (i.e. none) and
mentions the prevalance of `LIKELY`/`UNLIKELY` macros in many C/C++
projects.

Author: Aatch

text/0000-expect-intrinsic.md

@@ -5,7 +5,7 @@
 
 # Summary
 
-Provide an intrinsic function for hinting the likelyhood of branches being taken.
+Provide a pair of intrinsic functions for hinting the likelyhood of branches being taken.
 
 # Motivation
 
@@ -22,21 +22,34 @@ quintillion cases.
 
 # Detailed design
 
-Implement an `expect` intrinsic with the signature: `fn(bool, bool) -> bool`. The first argument is
-the condition being tested, the second argument is the expected result. The return value is the
-same as the first argument, meaning that `if foo == bar { .. }` can be simply replaced with
-`if expect(foo == bar, false) { .. }`.
+Implement a pair of intrinsics `likely` and `unlikely`, both with signature `fn(bool) -> bool`
+which hint at the probability of the passed value being true or false. Specifically, `likely` hints
+to the compiler that the passed value is likely to be true, and `unlikely` hints that it is likely
+to be false. Both functions simply return the value they are passed.
 
-The expected value is required to be a constant value.
+The primary reason for this design is that it reflects common usage of this general feature in many
+C and C++ projects, most of which define simple `LIKELY` and `UNLIKELY` macros around the gcc
+`__builtin_expect` intrinsic. It also provides the most flexibility, allowing branches on any
+condition to be hinted at, even if the process that produced the branched-upon value is
+complex. For why an equivalent to `__builtin_expect` is not being exposed, see the Alternatives
+section.
+
+There are no observable changes in behaviour from use of these intrinsics. It is valid to implement
+these intrinsics simply as the identity function. Though it is expected that the intrinsics provide
+information to the optimizer, that information is not guaranteed to change the decisions the
+optimiser makes.
 
 # Drawbacks
 
-The second argument is required to be a constant value, which can't be easily expressed.
+The intrinsics cannot be used to hint at arms in `match` expressions. However, given that hints
+would need to be variants, a simple intrinsic would not be sufficient for those purposes.
 
 # Alternatives
 
-Provide a pair of intrinsics `likely` and `unlikely`, these are the same as `expect` just with
-`true` and `false` substituted in for the expected value, respectively.
+Expose an `expect` intrinsic. This is what gcc/clang does with `__builtin_expect`. However there is
+a restriction that the second argument be a constant value, a requirement that is not easily
+expressible in Rust code. The split into `likely` and `unlikely` intrinsics reflects the strategy
+we have used for similar restrictions like the ordering constraint of the atomic intrinsics.
 
 # Unresolved questions