[Ceres]: Improve documentation of new features

docs/sophia_features.md

@@ -640,10 +640,16 @@ Sophia arbitrary-sized integers (FATE) also supports the following bitwise opera
 - arithmetic bitshift left (`x << n`)
 - arithmetic bitshift right (`x >> n`)
 
+Note: Arithmetic bitshift treats the number as a signed integer (in 2s
+complement), and "retains" the topmost bit. I.e. shifting in zeros if the
+topmost bit was 0, and ones if it was one.
+
 ## Bit fields
 
-Sophia integers do not support bit arithmetic. Instead there is a separate
-type `bits`. See the standard library [documentation](sophia_stdlib.md#bits).
+Originally Sophia integers did not support bit arithmetic. Instead we used a
+separate type `bits` (see the standard library
+[documentation](sophia_stdlib.md#bits)) - it is still provided as an
+alternative to bit arithmetic.
 
 A bit field can be of arbitrary size (but it is still represented by the
 corresponding integer, so setting very high bits can be expensive).

docs/sophia_stdlib.md

@@ -146,7 +146,7 @@ datatype pointee = AccountPt(address) | OraclePt(address)
 ```
 
 Note: on-chain there is a maximum length enforced for `DataPt`, it is 1024 bytes.
-Sophia itself does _not_ enforce this.
+Sophia itself does _not_ check for this.
 
 #### Functions
 
@@ -893,7 +893,8 @@ Int.to_bytes(n : int, size : int) : bytes()
 ```
 
 Casts the integer to a byte array with `size` bytes (big endian, truncating if
-necessary).
+necessary not preserving signedness). I.e. if you try to squeeze `-129` into a
+single byte that will be indistinguishable from `127`.
 
 
 ### Map
@@ -2474,7 +2475,9 @@ an integer. If the string doesn't contain a valid number `None` is returned.
 to_bytes(s : string) : bytes()
 ```
 
-Converts string into byte array.
+Converts string into byte array. String is UTF-8 encoded. I.e.
+`String.length(s)` is not guaranteed to be equal to
+`Bytes.size(String.to_bytes(s))`.
 
 #### sha3
 ```