first implementation of overloading of '='; missing: rewriting let/var sections

doc/manual/type_bound_ops.txt

@@ -21,12 +21,35 @@ helper distinct or object type has to be used for one pointer type.
 operator `=`
 ------------
 
-This operator is the assignment operator. Note that in the contexts 
-like ``let v = expr``, ``var v = expr``, ``parameter = defaultValue`` or for
-parameter passing no assignment is performed. The ``override`` pragma is
-optional for overriding ``=``.
+This operator is the assignment operator. Note that in the contexts
+like ``result = expr``, ``parameter = defaultValue`` or for
+parameter passing no assignment is performed. For a type ``T`` that has an
+overloaded assignment operator ``var v = T()`` is rewritten
+to ``var v: T; v = T()``; in other words ``var`` and ``let`` contexts do count
+as assignments.
+
+The assignment operator needs to be attached to an object or distinct
+type ``T``. Its signature has to be ``(var T, T)``. Example:
+
+.. code-block:: nim
+  type
+    Concrete = object
+      a, b: string
+
+  proc `=`(d: var Concrete; src: Concrete) =
+    shallowCopy(d.a, src.a)
+    shallowCopy(d.b, src.b)
+    echo "Concrete '=' called"
+
+  var x, y: array[0..2, Concrete]
+  var cA, cB: Concrete
+
+  var cATup, cBTup: tuple[x: int, ha: Concrete]
+
+  x = y
+  cA = cB
+  cATup = cBTup
 
-**Note**: Overriding of operator ``=`` is not yet implemented.
 
 
 destructors
@@ -36,12 +59,12 @@ A destructor must have a single parameter with a concrete type (the name of a
 generic type is allowed too). The name of the destructor has to be ``destroy``
 and it need to be annotated with the ``override`` pragma.
 
-``destroy(v)`` will be automatically invoked for every local stack 
+``destroy(v)`` will be automatically invoked for every local stack
 variable ``v`` that goes out of scope.
 
-If a structured type features a field with destructable type and 
+If a structured type features a field with destructable type and
 the user has not provided an explicit implementation, a destructor for the
-structured type will be automatically generated. Calls to any base class 
+structured type will be automatically generated. Calls to any base class
 destructors in both user-defined and generated destructors will be inserted.
 
 A destructor is attached to the type it destructs; expressions of this type
@@ -52,13 +75,13 @@ can then only be used in *destructible contexts* and as parameters:
     MyObj = object
       x, y: int
       p: pointer
-      
+
   proc destroy(o: var MyObj) {.override.} =
     if o.p != nil: dealloc o.p
-    
+
   proc open: MyObj =
     result = MyObj(x: 1, y: 2, p: alloc(3))
- 
+
   proc work(o: MyObj) =
     echo o.x
     # No destructor invoked here for 'o' as 'o' is a parameter.
@@ -68,7 +91,7 @@ can then only be used in *destructible contexts* and as parameters:
     var x = open()
     # valid: pass 'x' to some other proc:
     work(x)
-    
+
     # Error: usage of a type with a destructor in a non destructible context
     echo open()