Update docs

1 files changed, 21 insertions, 22 deletions

diff --git a/docs/operators.md b/docs/operators.md
index 6716b944..422c097b 100644
--- a/docs/operators.md
+++ b/docs/operators.md
@@ -28,14 +28,17 @@ to return a value that is the same type as the first argument and the second
 argument must be either the same type as the first argument or a number,
 depending on the specifications of the specific operator.
 
+If no suitable method is found with the appropriate types, a compiler error
+will be raised.
+
 ### Addition
 
 ```
 func plus(T, T)->T
 ```
 
-The `+` operator invokes the `plus()` method, which takes two objects of the
-same type and returns a new value of the same type.
+In an addition expression `a + b` between two objects of the same type, the
+method `a:plus(b)` will be invoked, which returns a new value of the same type.
 
 ### Subtraction
 
@@ -43,27 +46,20 @@ same type and returns a new value of the same type.
 func minus(T, T)->T
 ```
 
-The `-` operator invokes the `minus()` method, which takes two objects of the
-same type and returns a new value of the same type.
+In a subtraction expression `a - b` between two objects of the same type, the
+method `a:minus(b)` will be invoked, which returns a new value of the same type.
 
 ### Multiplication
 
 ```
 func times(T, T)->T
-```
-
-The `*` operator invokes the `times()` method, which takes two objects of the
-same type and returns a new value of the same type. This should _not_ be used
-to implement either a dot product or a cross product. Dot products and cross
-products should be implemented as explicitly named methods.
-
-```
 func scaled_by(T, N)->T
 ```
 
-In a multiplication expression, `a*b`, if either `a` or `b` has type `T` and
-the other has a numeric type `N` (either `Int8`, `Int16`, `Int32`, `Int`,
-`Num32`, or `Num`), then the method `scaled_by()` will be invoked.
+The multiplication expression `a * b` invokes either the `a:times(b)` method,
+if `a` and `b` are the same non-numeric type, or `a:scaled_by(b)` if `a` is
+non-numeric and `b` is numeric, or `b:scaled_by(a)` if `b` is non-numeric and
+`a` is numeric. In all cases, a new value of the non-numeric type is returned.
 
 ### Division
 
@@ -71,8 +67,8 @@ the other has a numeric type `N` (either `Int8`, `Int16`, `Int32`, `Int`,
 func divided_by(T, N)->T
 ```
 
-In a division expression, `a/b`, if `a` has type `T` and `b` has a numeric
-type `N`, then the method `divided_by()` will be invoked.
+In a division expression `a / b` the method `a:divided_by(b)` will be invoked
+if `a` has type `T` and `b` has a numeric type `N`.
 
 ### Exponentiation
 
@@ -80,8 +76,8 @@ type `N`, then the method `divided_by()` will be invoked.
 func power(T, N)->T
 ```
 
-In an exponentiation expression, `a^b`, if `a` has type `T` and `b` has a
-numeric type `N`, then the method `power()` will be invoked.
+In an exponentiation expression, `a ^ b`, if `a` has type `T` and `b` has a
+numeric type `N`, then the method `a:power(b)` will be invoked.
 
 ### Modulus
 
@@ -99,7 +95,8 @@ has a numeric type `N`, then the method `mod()` or `mod1()` will be invoked.
 func negative(T)->T
 ```
 
-In a unary negative expression `-x`, the method `negative()` will be invoked.
+In a unary negative expression `-x`, the method `negative()` will be invoked
+and will return a value of the same type.
 
 ### Bit Operations
 
@@ -113,9 +110,11 @@ func bit_xor(T, T)->T
 
 In a bit shifting expression, `a >> b` or `a << b`, if `a` has type `T` and `b`
 is an `Int`, then the method `left_shift()` or `right_shift()` will be invoked.
+A value of type `T` will be returned.
 
 In a bitwise binary operation `a and b`, `a or b`, or `a xor b`, then the
-method `bit_and()`, `bit_or()`, or `bit_xor()` will be invoked.
+method `bit_and()`, `bit_or()`, or `bit_xor()` will be invoked, assuming that
+`a` and `b` have the same type, `T`. A value of type `T` will be returned.
 
 ### Bitwise Negation
 
@@ -124,4 +123,4 @@ func negated(T)->T
 ```
 
 In a unary bitwise negation expression `not x`, the method `negated()` will be
-invoked.
+invoked and will return a value of the same type.