From c757e69c463f7da7b5655d561bc2aa672c055fd0 Mon Sep 17 00:00:00 2001
From: saem <saemghani+github@gmail.com>
Date: Sat, 30 Jul 2022 16:03:03 -0700
Subject: [PATCH] internals: sigmatch comments and code style

No behaviour changes, a few things should be more clear.

Added some `ast.newSymNode` overloads for convenience.
---
 compiler/ast/ast.nim      |  19 +-
 compiler/ast/types.nim    |  17 +-
 compiler/sem/sigmatch.nim | 781 +++++++++++++++++++++++++-------------
 3 files changed, 543 insertions(+), 274 deletions(-)

diff --git a/compiler/ast/ast.nim b/compiler/ast/ast.nim
index 04cf8d4025e..ebe61c51d3e 100644
--- a/compiler/ast/ast.nim
+++ b/compiler/ast/ast.nim
@@ -200,17 +200,18 @@ proc newSymNode2*(sym: PSym, info: TLineInfo): PNode =
     result.typ = sym.typ
     result.info = info
 
-proc newSymNode*(sym: PSym): PNode =
-  result = newNode(nkSym)
+proc newSymNodeIT*(sym: PSym, info: TLineInfo, typ: PType): PNode =
+  ## create a new sym node with the supplied `info` and `typ`
+  result = newNodeIT(nkSym, info, typ)
   result.sym = sym
-  result.typ = sym.typ
-  result.info = sym.info
 
-proc newSymNode*(sym: PSym, info: TLineInfo): PNode =
-  result = newNode(nkSym)
-  result.sym = sym
-  result.typ = sym.typ
-  result.info = info
+proc newSymNode*(sym: PSym, info: TLineInfo): PNode {.inline.} =
+  ## create a new sym node from `sym` with its type and supplied `info`
+  result = newSymNodeIT(sym, info, sym.typ)
+
+proc newSymNode*(sym: PSym): PNode {.inline.} =
+  ## create a new sym node from `sym` with its info and type
+  result = newSymNode(sym, sym.info)
 
 proc newIntNode*(kind: TNodeKind, intVal: BiggestInt): PNode =
   result = newNode(kind)
diff --git a/compiler/ast/types.nim b/compiler/ast/types.nim
index 63d45d685fe..bf37eb50722 100644
--- a/compiler/ast/types.nim
+++ b/compiler/ast/types.nim
@@ -1163,13 +1163,20 @@ proc skipConvTakeType*(n: PNode): PNode =
   result.typ = n.typ
 
 proc isEmptyContainer*(t: PType): bool =
+  ## true if the type is considered a container and is empty, otherwise false.
+  ## container types are untyped, nil, `array/seq/set/etc[T]` with an emtpy
+  ## type for `T`.
   case t.kind
-  of tyUntyped, tyNil: result = true
-  of tyArray: result = t[1].kind == tyEmpty
+  of tyUntyped, tyNil:
+    true
+  of tyArray:
+    t[1].kind == tyEmpty
   of tySet, tySequence, tyOpenArray, tyVarargs:
-    result = t[0].kind == tyEmpty
-  of tyGenericInst, tyAlias, tySink: result = isEmptyContainer(t.lastSon)
-  else: result = false
+    t[0].kind == tyEmpty
+  of tyGenericInst, tyAlias, tySink:
+    isEmptyContainer(t.lastSon)
+  else:
+    false
 
 proc takeType*(formal, arg: PType; g: ModuleGraph; idgen: IdGenerator): PType =
   # param: openArray[string] = []
diff --git a/compiler/sem/sigmatch.nim b/compiler/sem/sigmatch.nim
index a05619d6bfd..0f9ac10779b 100644
--- a/compiler/sem/sigmatch.nim
+++ b/compiler/sem/sigmatch.nim
@@ -21,6 +21,7 @@ import
     idents,
     trees,
     lineinfos,
+    errorreporting,
     errorhandling,
     reports,
   ],
@@ -992,9 +993,11 @@ typeRel can be used to establish various relationships between types:
       case f.kind
       of tyGenericParam:
         var prev = PType(idTableGet(c.bindings, f))
-        if prev != nil: candidate = prev
+        if prev != nil:
+          candidate = prev
       of tyFromExpr:
         let computedType = tryResolvingStaticExpr(c, f.n).typ
+
         case computedType.kind
         of tyTypeDesc:
           candidate = computedType.base
@@ -1055,8 +1058,11 @@ typeRel can be used to establish various relationships between types:
     result = isGeneric
     for branch in a.sons:
       let x = typeRel(c, f, branch, flags + {trDontBind})
-      if x == isNone: return isNone
-      if x < result: result = x
+      if x == isNone:
+        result = isNone
+        break
+      elif x < result:
+        result = x
     return result
 
   of tyAnd:
@@ -1071,7 +1077,8 @@ typeRel can be used to establish various relationships between types:
     return isNone
 
   of tyIterable:
-    if f.kind != tyIterable: return isNone
+    if f.kind != tyIterable:
+      return isNone
   of tyNot:
     case f.kind
     of tyNot:
@@ -1088,8 +1095,8 @@ typeRel can be used to establish various relationships between types:
              else: isNone
 
   of tyAnything:
-    if f.kind == tyAnything: return isGeneric
-    else: return isNone
+    return if f.kind == tyAnything: isGeneric
+           else: isNone
 
   of tyUserTypeClass, tyUserTypeClassInst:
     if c.c.matchedConcept != nil and c.c.matchedConcept.depth <= 4:
@@ -1099,18 +1106,25 @@ typeRel can be used to establish various relationships between types:
       let x = typeRel(c, a, f, flags + {trDontBind})
       if x >= isGeneric:
         return isGeneric
-  else: discard
+  else:
+    discard
 
   case f.kind
   of tyEnum:
-    if a.kind == f.kind and sameEnumTypes(f, a): result = isEqual
-    elif sameEnumTypes(f, skipTypes(a, {tyRange})): result = isSubtype
+    if a.kind == f.kind and sameEnumTypes(f, a):
+      result = isEqual
+    elif sameEnumTypes(f, skipTypes(a, {tyRange})):
+      result = isSubtype
   of tyBool, tyChar:
-    if a.kind == f.kind: result = isEqual
-    elif skipTypes(a, {tyRange}).kind == f.kind: result = isSubtype
+    if a.kind == f.kind:
+      result = isEqual
+    elif skipTypes(a, {tyRange}).kind == f.kind:
+      result = isSubtype
   of tyRange:
     if a.kind == f.kind:
-      if f.base.kind == tyNone: return isGeneric
+      if f.base.kind == tyNone:
+        return isGeneric
+
       result = typeRel(c, base(f), base(a), flags)
       # bugfix: accept integer conversions here
       #if result < isGeneric: result = isNone
@@ -1142,29 +1156,39 @@ typeRel can be used to establish various relationships between types:
   of tyFloat64:  result = handleFloatRange(f, a)
   of tyFloat128: result = handleFloatRange(f, a)
   of tyVar, tyLent:
-    if aOrig.kind == f.kind: result = typeRel(c, f.base, aOrig.base, flags)
-    else: result = typeRel(c, f.base, aOrig, flags + {trNoCovariance})
+    result =
+      if aOrig.kind == f.kind:
+        typeRel(c, f.base, aOrig.base, flags)
+      else:
+        typeRel(c, f.base, aOrig, flags + {trNoCovariance})
+
     subtypeCheck()
   of tyArray:
     case a.kind
     of tyArray:
-      var fRange = f[0]
-      var aRange = a[0]
+      var
+        fRange = f[0]
+        aRange = a[0]
+      
       if fRange.kind == tyGenericParam:
-        var prev = PType(idTableGet(c.bindings, fRange))
+        let prev = PType(idTableGet(c.bindings, fRange))
         if prev == nil:
           put(c, fRange, a[0])
           fRange = a
         else:
           fRange = prev
-      let ff = f[1].skipTypes({tyTypeDesc})
-      # This typeDesc rule is wrong, see bug #7331
-      let aa = a[1] #.skipTypes({tyTypeDesc})
-
-      if f[0].kind != tyGenericParam and aa.kind == tyEmpty:
-        result = isGeneric
-      else:
-        result = typeRel(c, ff, aa, flags)
+      
+      let
+        ff = f[1].skipTypes({tyTypeDesc})
+        aa = a[1] #.skipTypes({tyTypeDesc})
+                  # This typeDesc rule is wrong, see:
+                  # https://github.com/nim-lang/nim/issues/7331
+
+      result =
+        if f[0].kind != tyGenericParam and aa.kind == tyEmpty:
+          isGeneric
+        else:
+          typeRel(c, ff, aa, flags)
 
       if result < isGeneric:
         if nimEnableCovariance and
@@ -1182,24 +1206,29 @@ typeRel can be used to establish various relationships between types:
       else:
         if lengthOrd(c.c.config, fRange) != lengthOrd(c.c.config, aRange):
           result = isNone
-    else: discard
+    else:
+      discard
   of tyUncheckedArray:
     if a.kind == tyUncheckedArray:
       result = typeRel(c, base(f), base(a), flags)
-      if result < isGeneric: result = isNone
-    else: discard
+      if result < isGeneric:
+        result = isNone
+    else:
+      discard
   of tyOpenArray, tyVarargs:
     # varargs[untyped] is special too but handled earlier. So we only need to
     # handle varargs[typed]:
     if f.kind == tyVarargs:
       if tfVarargs in a.flags:
         return typeRel(c, f.base, a.lastSon, flags)
-      if f[0].kind == tyTyped: return
+      if f[0].kind == tyTyped:
+        return
 
     template matchArrayOrSeq(aBase: PType) =
-      let ff = f.base
-      let aa = aBase
-      let baseRel = typeRel(c, ff, aa, flags)
+      let
+        ff = f.base
+        aa = aBase
+        baseRel = typeRel(c, ff, aa, flags)
       if baseRel >= isGeneric:
         result = isConvertible
       elif nimEnableCovariance and
@@ -1211,7 +1240,8 @@ typeRel can be used to establish various relationships between types:
     case a.kind
     of tyOpenArray, tyVarargs:
       result = typeRel(c, base(f), base(a), flags)
-      if result < isGeneric: result = isNone
+      if result < isGeneric:
+        result = isNone
     of tyArray:
       if (f[0].kind != tyGenericParam) and (a[1].kind == tyEmpty):
         return isSubtype
@@ -1227,15 +1257,17 @@ typeRel can be used to establish various relationships between types:
         elif f[0].kind == tyGenericParam and a.len > 0 and
             typeRel(c, base(f), base(a), flags) >= isGeneric:
           result = isConvertible
-    else: discard
+    else:
+      discard
   of tySequence:
     case a.kind
     of tySequence:
       if (f[0].kind != tyGenericParam) and (a[0].kind == tyEmpty):
         result = isSubtype
       else:
-        let ff = f[0]
-        let aa = a[0]
+        let
+          ff = f[0]
+          aa = a[0]
         result = typeRel(c, ff, aa, flags)
         if result < isGeneric:
           if nimEnableCovariance and
@@ -1247,16 +1279,24 @@ typeRel can be used to establish various relationships between types:
             result = isNone
         elif tfNotNil in f.flags and tfNotNil notin a.flags:
           result = isNilConversion
-    of tyNil: result = isNone
-    else: discard
+    of tyNil:
+      result = isNone
+    else:
+      discard
   of tyOrdinal:
     if isOrdinalType(a, allowEnumWithHoles = optNimV1Emulation in c.c.config.globalOptions):
-      var x = if a.kind == tyOrdinal: a[0] else: a
+      var x =
+        if a.kind == tyOrdinal:
+          a[0]
+        else:
+          a
+      
       if f[0].kind == tyNone:
         result = isGeneric
       else:
         result = typeRel(c, f[0], x, flags)
-        if result < isGeneric: result = isNone
+        if result < isGeneric:
+          result = isNone
     elif a.kind == tyGenericParam:
       result = isGeneric
   of tyForward:
@@ -1264,9 +1304,11 @@ typeRel can be used to establish various relationships between types:
     result = isNone
   of tyNil:
     skipOwned(a)
-    if a.kind == f.kind: result = isEqual
+    if a.kind == f.kind:
+      result = isEqual
   of tyTuple:
-    if a.kind == tyTuple: result = recordRel(c, f, a)
+    if a.kind == tyTuple:
+      result = recordRel(c, f, a)
   of tyObject:
     if a.kind == tyObject:
       if sameObjectTypes(f, a):
@@ -1280,12 +1322,16 @@ typeRel can be used to establish various relationships between types:
   of tyDistinct:
     a = a.skipTypes({tyOwned, tyGenericInst, tyRange})
     if a.kind == tyDistinct:
-      if sameDistinctTypes(f, a): result = isEqual
-      #elif f.base.kind == tyAnything: result = isGeneric  # issue 4435
-      elif c.coerceDistincts: result = typeRel(c, f.base, a, flags)
+      if sameDistinctTypes(f, a):
+        result = isEqual
+      #elif f.base.kind == tyAnything:
+      #  result = isGeneric  # see https://github.com/nim-lang/nim/issues/4435
+      elif c.coerceDistincts:
+        result = typeRel(c, f.base, a, flags)
     elif a.kind == tyNil and f.base.kind in NilableTypes:
       result = f.allowsNil # XXX remove this typing rule, it is not in the spec
-    elif c.coerceDistincts: result = typeRel(c, f.base, a, flags)
+    elif c.coerceDistincts:
+      result = typeRel(c, f.base, a, flags)
   of tySet:
     if a.kind == tySet:
       if f[0].kind != tyGenericParam and a[0].kind == tyEmpty:
@@ -1303,16 +1349,24 @@ typeRel can be used to establish various relationships between types:
     skipOwned(a)
     if a.kind == f.kind:
       # ptr[R, T] can be passed to ptr[T], but not the other way round:
-      if a.len < f.len: return isNone
+      if a.len < f.len:
+        return isNone
+      
       for i in 0..<f.len-1:
-        if typeRel(c, f[i], a[i], flags) == isNone: return isNone
+        if typeRel(c, f[i], a[i], flags) == isNone:
+          return isNone
+      
       result = typeRel(c, f.lastSon, a.lastSon, flags + {trNoCovariance})
       subtypeCheck()
-      if result <= isIntConv: result = isNone
+      
+      if result <= isIntConv:
+        result = isNone
       elif tfNotNil in f.flags and tfNotNil notin a.flags:
         result = isNilConversion
-    elif a.kind == tyNil: result = f.allowsNil
-    else: discard
+    elif a.kind == tyNil:
+      result = f.allowsNil
+    else:
+      discard
   of tyProc:
     skipOwned(a)
     result = procTypeRel(c, f, a)
@@ -1322,8 +1376,10 @@ typeRel can be used to establish various relationships between types:
     case a.kind
     of tyOwned:
       result = typeRel(c, lastSon(f), lastSon(a), flags)
-    of tyNil: result = f.allowsNil
-    else: discard
+    of tyNil:
+      result = f.allowsNil
+    else:
+      discard
   of tyPointer:
     skipOwned(a)
     case a.kind
@@ -1332,15 +1388,18 @@ typeRel can be used to establish various relationships between types:
         result = isNilConversion
       else:
         result = isEqual
-    of tyNil: result = f.allowsNil
+    of tyNil:
+      result = f.allowsNil
     of tyProc:
       if a.callConv != ccClosure: result = isConvertible
     of tyPtr:
       # 'pointer' is NOT compatible to regionized pointers
       # so 'dealloc(regionPtr)' fails:
       if a.len == 1: result = isConvertible
-    of tyCstring: result = isConvertible
-    else: discard
+    of tyCstring:
+      result = isConvertible
+    else:
+      discard
   of tyString:
     case a.kind
     of tyString:
@@ -1348,8 +1407,10 @@ typeRel can be used to establish various relationships between types:
         result = isNilConversion
       else:
         result = isEqual
-    of tyNil: result = isNone
-    else: discard
+    of tyNil:
+      result = isNone
+    else:
+      discard
   of tyCstring:
     # conversion from string to cstring is automatic:
     case a.kind
@@ -1358,29 +1419,35 @@ typeRel can be used to establish various relationships between types:
         result = isNilConversion
       else:
         result = isEqual
-    of tyNil: result = f.allowsNil
-    of tyString: result = isConvertible
+    of tyNil:
+      result = f.allowsNil
+    of tyString:
+      result = isConvertible
     of tyPtr:
       # ptr[Tag, char] is not convertible to 'cstring' for now:
       if a.len == 1:
         let pointsTo = a[0].skipTypes(abstractInst)
-        if pointsTo.kind == tyChar: result = isConvertible
+        if pointsTo.kind == tyChar:
+          result = isConvertible
         elif pointsTo.kind == tyUncheckedArray and pointsTo[0].kind == tyChar:
           result = isConvertible
         elif pointsTo.kind == tyArray and firstOrd(nil, pointsTo[0]) == 0 and
             skipTypes(pointsTo[0], {tyRange}).kind in {tyInt..tyInt64} and
             pointsTo[1].kind == tyChar:
           result = isConvertible
-    else: discard
+    else:
+      discard
 
   of tyEmpty, tyVoid:
-    if a.kind == f.kind: result = isEqual
+    if a.kind == f.kind:
+      result = isEqual
 
   of tyAlias, tySink:
     result = typeRel(c, lastSon(f), a, flags)
 
   of tyIterable:
-    if a.kind == tyIterable:
+    case a.kind
+    of tyIterable:
       if f.len == 1:
         result = typeRel(c, lastSon(f), lastSon(a), flags)
       else:
@@ -1408,10 +1475,14 @@ typeRel can be used to establish various relationships between types:
         result = isEqual
 
         for i in 1..<rootf.len-1:
-          let ff = rootf[i]
-          let aa = roota[i]
-          let res = typeRel(c, ff, aa, nextFlags)
-          if res != isNone and res != isEqual: result = isGeneric
+          let
+            ff = rootf[i]
+            aa = roota[i]
+            res = typeRel(c, ff, aa, nextFlags)
+          
+          if res != isNone and res != isEqual:
+            result = isGeneric
+          
           if res notin {isEqual, isGeneric}:
             if trNoCovariance notin flags and ff.kind == aa.kind:
               let paramFlags = rootf.base[i-1].flags
@@ -1428,12 +1499,14 @@ typeRel can be used to establish various relationships between types:
                 continue
 
             return isNone
-        if prev == nil: put(c, f, a)
+        if prev == nil:
+          put(c, f, a)
       else:
         let fKind = rootf.lastSon.kind
         if fKind in {tyAnd, tyOr}:
           result = typeRel(c, lastSon(f), a, flags)
-          if result != isNone: put(c, f, a)
+          if result != isNone:
+            put(c, f, a)
           return
 
         var aAsObject = roota.lastSon
@@ -1472,9 +1545,11 @@ typeRel can be used to establish various relationships between types:
     var x = a.skipGenericAlias
     let concpt = f[0].skipTypes({tyGenericBody})
     var preventHack = false
+
     if x.kind == tyOwned and f[0].kind != tyOwned:
       preventHack = true
       x = x.lastSon
+
     # XXX: This is very hacky. It should be moved back into liftTypeParam
     if x.kind in {tyGenericInst, tyArray} and
       c.calleeSym != nil and
@@ -1495,20 +1570,26 @@ typeRel can be used to establish various relationships between types:
         c.c.graph.config.internalAssert(x[i].kind != tyGenericParam, "wrong instantiated type!")
 
         if typeRel(c, f[i], x[i], flags) <= isSubtype:
-          # Workaround for regression #4589
-          if f[i].kind != tyTypeDesc: return
+          # Workaround for https://github.com/nim-lang/nim/issues/4589
+          if f[i].kind != tyTypeDesc:
+            return
 
       result = isGeneric
     else:
-      let genericBody = f[0]
-      var askip = skippedNone
-      var fskip = skippedNone
-      let aobj = x.skipToObject(askip)
-      let fobj = genericBody.lastSon.skipToObject(fskip)
-      var depth = -1
+      var
+        askip = skippedNone
+        fskip = skippedNone
+        depth = -1
+      let
+        genericBody = f[0]
+        aobj = x.skipToObject(askip)
+        fobj = genericBody.lastSon.skipToObject(fskip)
+      
       if fobj != nil and aobj != nil and askip == fskip:
         depth = isObjectSubtype(c, aobj, fobj, f)
+      
       result = typeRel(c, genericBody, x, flags)
+      
       if result != isNone:
         # see tests/generics/tgeneric3.nim for an example that triggers this
         # piece of code:
@@ -1553,10 +1634,13 @@ typeRel can be used to establish various relationships between types:
       result = isEqual
       for branch in f.sons:
         let x = typeRel(c, branch, aOrig, flags)
-        if x < isSubtype: return isNone
+        if x < isSubtype:
+          return isNone
         # 'and' implies minimum matching result:
-        if x < result: result = x
-      if result > isGeneric: result = isGeneric
+        if x < result:
+          result = x
+      if result > isGeneric:
+        result = isGeneric
       bindingRet result
 
   of tyOr:
@@ -1570,9 +1654,11 @@ typeRel can be used to establish various relationships between types:
         maxInheritance = max(maxInheritance, c.inheritancePenalty)
 
         # 'or' implies maximum matching result:
-        if x > result: result = x
+        if x > result:
+          result = x
       if result >= isSubtype:
-        if result > isGeneric: result = isGeneric
+        if result > isGeneric:
+          result = isGeneric
         bindingRet result
       else:
         result = isNone
@@ -1595,10 +1681,12 @@ typeRel can be used to establish various relationships between types:
 
   of tyBuiltInTypeClass:
     considerPreviousT:
-      let targetKind = f[0].kind
-      let effectiveArgType = a.skipTypes({tyRange, tyGenericInst,
-                                          tyBuiltInTypeClass, tyAlias, tySink, tyOwned})
-      let typeClassMatches = targetKind == effectiveArgType.kind and
+      let
+        targetKind = f[0].kind
+        effectiveArgType = a.skipTypes({tyRange, tyGenericInst,
+                                        tyBuiltInTypeClass, tyAlias,
+                                        tySink, tyOwned})
+        typeClassMatches = targetKind == effectiveArgType.kind and
                              not effectiveArgType.isEmptyContainer
       if typeClassMatches or
         (targetKind in {tyProc, tyPointer} and effectiveArgType.kind == tyNil):
@@ -1612,11 +1700,15 @@ typeRel can be used to establish various relationships between types:
       result = typeRel(c, f.lastSon, a, flags)
     else:
       considerPreviousT:
-        if aOrig == f: return isEqual
+        if aOrig == f:
+          return isEqual
+        
         var matched = matchUserTypeClass(c, f, aOrig)
+        
         if matched != nil:
           bindConcreteTypeToUserTypeClass(matched, a)
-          if doBind: put(c, f, matched)
+          if doBind:
+            put(c, f, matched)
           result = isGeneric
         elif a.len > 0 and a.lastSon == f:
           # Needed for checking `Y` == `Addable` in the following
@@ -1632,15 +1724,19 @@ typeRel can be used to establish various relationships between types:
 
   of tyCompositeTypeClass:
     considerPreviousT:
-      let roota = a.skipGenericAlias
-      let rootf = f.lastSon.skipGenericAlias
+      let
+        roota = a.skipGenericAlias
+        rootf = f.lastSon.skipGenericAlias
       if a.kind == tyGenericInst and roota.base == rootf.base:
         for i in 1..<rootf.len-1:
-          let ff = rootf[i]
-          let aa = roota[i]
+          let
+            ff = rootf[i]
+            aa = roota[i]
           result = typeRel(c, ff, aa, flags)
-          if result == isNone: return
-          if ff.kind == tyRange and result != isEqual: return isNone
+          if result == isNone:
+            return
+          if ff.kind == tyRange and result != isEqual:
+            return isNone
       else:
         result = typeRel(c, rootf.lastSon, a, flags)
       if result != isNone:
@@ -1672,7 +1768,8 @@ typeRel can be used to establish various relationships between types:
               # If the constraint is a genericParam or typeClass this isGeneric
               return isGeneric
             result = typeRel(c, f.base, aa, flags)
-            if result > isGeneric: result = isGeneric
+            if result > isGeneric:
+              result = isGeneric
         elif c.isNoCall:
           if doBindGP:
             let concrete = concreteType(c, a, f)
@@ -1870,13 +1967,14 @@ proc getInstantiatedType(c: PContext, arg: PNode, m: TCandidate,
 proc implicitConv(kind: TNodeKind, f: PType, arg: PNode, m: TCandidate,
                   c: PContext): PNode =
   result = newNodeI(kind, arg.info)
-  if containsGenericType(f):
-    if not m.hasFauxMatch:
-      result.typ = getInstantiatedType(c, arg, m, f).skipTypes({tySink})
+  result.typ =
+    if containsGenericType(f):
+      if not m.hasFauxMatch:
+        getInstantiatedType(c, arg, m, f).skipTypes({tySink})
+      else:
+        errorType(c)
     else:
-      result.typ = errorType(c)
-  else:
-    result.typ = f.skipTypes({tySink})
+      f.skipTypes({tySink})
 
   c.graph.config.internalAssert(result.typ != nil, arg.info, "implicitConv")
 
@@ -1884,107 +1982,139 @@ proc implicitConv(kind: TNodeKind, f: PType, arg: PNode, m: TCandidate,
   result.add arg
 
 proc isLValue(c: PContext; n: PNode): bool {.inline.} =
-  let aa = isAssignable(nil, n)
-  case aa
+  case isAssignable(nil, n)
   of arLValue, arLocalLValue, arStrange:
-    result = true
+    true
   of arDiscriminant:
-    result = c.inUncheckedAssignSection > 0
+    c.inUncheckedAssignSection > 0
   else:
-    result = false
+    false
 
 proc userConvMatch(c: PContext, m: var TCandidate, f, a: PType,
                    arg: PNode): PNode =
   result = nil
+
   for i in 0..<c.converters.len:
-    var src = c.converters[i].typ[1]
-    var dest = c.converters[i].typ[0]
+    var
+      src = c.converters[i].typ[1]
+      dest = c.converters[i].typ[0]
+
     # for generic type converters we need to check 'src <- a' before
     # 'f <- dest' in order to not break the unification:
     # see tests/tgenericconverter:
     let srca = typeRel(m, src, a)
-    if srca notin {isEqual, isGeneric, isSubtype}: continue
+    
+    if srca notin {isEqual, isGeneric, isSubtype}:
+      continue
 
     # What's done below matches the logic in ``matchesAux``
     let constraint = c.converters[i].typ.n[1].sym.constraint
+
     if not constraint.isNil and not matchNodeKinds(constraint, arg):
       continue
+
     if src.kind in {tyVar, tyLent} and not isLValue(c, arg):
       continue
 
     let destIsGeneric = containsGenericType(dest)
+
     if destIsGeneric:
       dest = generateTypeInstance(c, m.bindings, arg, dest)
+
     let fdest = typeRel(m, f, dest)
-    if fdest in {isEqual, isGeneric} and not (dest.kind == tyLent and f.kind in {tyVar}):
+
+    if fdest in {isEqual, isGeneric} and
+       not (dest.kind == tyLent and f.kind in {tyVar}):
       markUsed(c, arg.info, c.converters[i])
-      var s = newSymNode(c.converters[i])
-      s.typ = c.converters[i].typ
-      s.info = arg.info
-      result = newNodeIT(nkHiddenCallConv, arg.info, dest)
-      result.add s
+
+      let conv = c.converters[i]
+
       # We build the call expression by ourselves in order to avoid passing this
-      # expression trough the semantic check phase once again so let's make sure
-      # it is correct
-      var param: PNode = nil
-      if srca == isSubtype:
-        param = implicitConv(nkHiddenSubConv, src, copyTree(arg), m, c)
-      elif src.kind in {tyVar}:
-        # Analyse the converter return type
-        param = newNodeIT(nkHiddenAddr, arg.info, s.typ[1])
-        param.add copyTree(arg)
-      else:
-        param = copyTree(arg)
-      result.add param
+      # expression through the semantic check phase once again so let's make
+      # sure it is correct
+      result = newTreeIT(nkHiddenCallConv, arg.info, dest,
+                # the converter sym
+                newSymNodeIT(conv, arg.info, conv.typ),
+                # arg for the converter call
+                if srca == isSubtype:
+                  implicitConv(nkHiddenSubConv, src, copyTree(arg), m, c)
+                elif src.kind in {tyVar}:
+                  # Analyse the converter return type
+                  newTreeIT(nkHiddenAddr, arg.info, conv.typ[1], copyTree(arg))
+                else:
+                  copyTree(arg))
 
       if dest.kind in {tyVar, tyLent}:
         dest.flags.incl tfVarIsPtr
         result = newDeref(result)
 
       inc(m.convMatches)
+
       if not m.genericConverter:
         m.genericConverter = srca == isGeneric or destIsGeneric
+
       return result
 
 proc localConvMatch(c: PContext, m: var TCandidate, f, a: PType,
                     arg: PNode): PNode =
   # arg.typ can be nil in 'suggest':
-  if isNil(arg.typ): return nil
+  if isNil(arg.typ):
+    return nil
 
   # sem'checking for 'echo' needs to be re-entrant:
-  # XXX we will revisit this issue after 0.10.2 is released
-  if f == arg.typ and arg.kind == nkHiddenStdConv: return arg
+  # xxx: sem idempotency issue
+  if f == arg.typ and arg.kind == nkHiddenStdConv:
+    return arg
 
   var call = newNodeI(nkCall, arg.info)
   call.add(f.n.copyTree)
   call.add(arg.copyTree)
+
   # XXX: This would be much nicer if we don't use `semTryExpr` and
-  # instead we directly search for overloads with `resolveOverloads`:
+  # instead we directly search for overloads with `resolveOverloads`.
+  # but converters are special and that causes all sorts of issues :/
   result = c.semTryExpr(c, call, {efNoSem2Check})
 
   if result != nil:
-    if result.typ == nil: return nil
-    # bug #13378, ensure we produce a real generic instantiation:
+    if result.typ == nil:
+      return nil
+
+    # ensure we produce a real generic instantiation, see bug
+    # https://github.com/nim-lang/nim/issues/13378:
     result = c.semExpr(c, call)
+
     # resulting type must be consistent with the other arguments:
     var r = typeRel(m, f[0], result.typ)
-    if r < isGeneric: return nil
-    if result.kind == nkCall: result.transitionSonsKind(nkHiddenCallConv)
+    
+    if r < isGeneric:
+      return nil
+
+    if result.kind == nkCall:
+      result.transitionSonsKind(nkHiddenCallConv)
+
     inc(m.convMatches)
+
     if r == isGeneric:
       result.typ = getInstantiatedType(c, arg, m, base(f))
+
     m.baseTypeMatch = true
 
 proc incMatches(m: var TCandidate; r: TTypeRelation; convMatch = 1) =
   case r
-  of isConvertible, isIntConv: inc(m.convMatches, convMatch)
-  of isSubtype, isSubrange: inc(m.subtypeMatches)
-  of isGeneric, isInferred, isBothMetaConvertible: inc(m.genericMatches)
-  of isFromIntLit: inc(m.intConvMatches, 256)
+  of isConvertible, isIntConv:
+    inc(m.convMatches, convMatch)
+  of isSubtype, isSubrange:
+    inc(m.subtypeMatches)
+  of isGeneric, isInferred, isBothMetaConvertible:
+    inc(m.genericMatches)
+  of isFromIntLit:
+    inc(m.intConvMatches, 256)
   of isInferredConvertible:
     inc(m.convMatches)
-  of isEqual: inc(m.exactMatches)
-  of isNone: discard
+  of isEqual:
+    inc(m.exactMatches)
+  of isNone:
+    discard
 
 template matchesVoidProc(t: PType): bool =
   (t.kind == tyProc and t.len == 1 and t[0] == nil) or
@@ -2050,40 +2180,49 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
     # directly into typeRel using return-like templates
     incMatches(m, r)
     result =
-      if f.kind == tyTyped:
-        arg
-      elif f.kind == tyTypeDesc:
+      case f.kind
+      of tyTyped, tyTypeDesc:
         arg
-      elif f.kind == tyStatic and arg.typ.n != nil:
-        arg.typ.n
+      of tyStatic:
+        if arg.typ.n.isNil:  # no value on the type
+          argSemantized
+        else:                # value on the type
+          arg.typ.n
       else:
         argSemantized
     return
 
+  var
+    bothMetaCounter = 0
+      ## bothMetaCounter is for safety to avoid any infinite loop,
+      ## we don't have any example when it is needed.
+    lastBindingsLength = -1
+      ## lastBindingsLenth use to track whether m.bindings remains the same,
+      ## because in that case there is no point in continuing.
+  
   # If r == isBothMetaConvertible then we rerun typeRel.
-  # bothMetaCounter is for safety to avoid any infinite loop,
-  #  I don't have any example when it is needed.
-  # lastBindingsLenth is used to check whether m.bindings remains the same,
-  #  because in that case there is no point in continuing.
-  var bothMetaCounter = 0
-  var lastBindingsLength = -1
   while r == isBothMetaConvertible and
       lastBindingsLength != m.bindings.counter and
-      bothMetaCounter < 100:
+      bothMetaCounter < 100:                        # ensure termination
+
     lastBindingsLength = m.bindings.counter
     inc(bothMetaCounter)
-    if arg.kind in {nkProcDef, nkFuncDef, nkIteratorDef} + nkLambdaKinds:
+
+    case arg.kind
+    of nkProcDef, nkFuncDef, nkIteratorDef, nkLambdaKinds:
       result = c.semInferredLambda(c, m.bindings, arg)
-    elif arg.kind != nkSym:
-      result = nil
-      return
-    else:
+    of nkSym:
       let inferred = c.semGenerateInstance(c, arg.sym, m.bindings, arg.info)
       result = newSymNode(inferred, arg.info)
+    else:
+      result = nil
+      return
+
     inc(m.convMatches)
     arg = result
     r = typeRel(m, f, arg.typ)
 
+  # now check the relation result in `r`
   case r
   of isConvertible:
     inc(m.convMatches)
@@ -2091,36 +2230,48 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
   of isIntConv:
     # I'm too lazy to introduce another ``*matches`` field, so we conflate
     # ``isIntConv`` and ``isIntLit`` here:
+    # xxx: this should likely be disambiguated
     inc(m.intConvMatches)
     result = implicitConv(nkHiddenStdConv, f, arg, m, c)
   of isSubtype:
     inc(m.subtypeMatches)
-    if f.kind == tyTypeDesc:
-      result = arg
-    else:
-      result = implicitConv(nkHiddenSubConv, f, arg, m, c)
+    result =
+      case f.kind
+      of tyTypeDesc:
+        arg
+      else:
+        implicitConv(nkHiddenSubConv, f, arg, m, c)
   of isSubrange:
     inc(m.subtypeMatches)
-    if f.kind in {tyVar}:
-      result = arg
-    else:
-      result = implicitConv(nkHiddenStdConv, f, arg, m, c)
+    result =
+      case f.kind
+      of tyVar:
+        arg
+      else:
+        implicitConv(nkHiddenStdConv, f, arg, m, c)
   of isInferred, isInferredConvertible:
-    if arg.kind in {nkProcDef, nkFuncDef, nkIteratorDef} + nkLambdaKinds:
+    case arg.kind
+    of nkProcDef, nkFuncDef, nkIteratorDef, nkLambdaKinds:
       result = c.semInferredLambda(c, m.bindings, arg)
-    elif arg.kind != nkSym:
-      result = nil
-      return
-    else:
+    of nkSym:
       let inferred = c.semGenerateInstance(c, arg.sym, m.bindings, arg.info)
       result = newSymNode(inferred, arg.info)
-    if r == isInferredConvertible:
+    else:
+      result = nil
+      return
+
+    case r
+    of isInferredConvertible:
       inc(m.convMatches)
       result = implicitConv(nkHiddenStdConv, f, result, m, c)
     else:
       inc(m.genericMatches)
   of isGeneric:
     inc(m.genericMatches)
+    # xxx: this logic isn't more linear likely because we don't differentiate:
+    #      - array/seq/etc as universal type (kind?), vs 
+    #      - array/seq/etc as a monomorph, vs
+    #      - array/seq/etc instantiated
     if arg.typ == nil:
       result = arg
     elif skipTypes(arg.typ, abstractVar-{tyTypeDesc}).kind == tyTuple or
@@ -2137,6 +2288,7 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
   of isFromIntLit:
     # too lazy to introduce another ``*matches`` field, so we conflate
     # ``isIntConv`` and ``isIntLit`` here:
+    # xxx: this should likely be disambiguated, subtle impact everywhere
     inc(m.intConvMatches, 256)
     result = implicitConv(nkHiddenStdConv, f, arg, m, c)
   of isEqual:
@@ -2147,6 +2299,7 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
       result = implicitConv(nkHiddenSubConv, f, arg, m, c)
   of isNone:
     # do not do this in ``typeRel`` as it then can't infer T in ``ref T``:
+    # xxx: likely a latent bug, as tyError is simply a const equal to tyProxy
     if a.kind in {tyProxy, tyUnknown}:
       inc(m.genericMatches)
       m.fauxMatch = a.kind
@@ -2154,17 +2307,29 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
       return
     elif a.kind == tyVoid and f.matchesVoidProc and arg.kind == nkStmtList:
       # lift do blocks without params to lambdas
-      let p = c.graph
-      let lifted = c.semExpr(c, newProcNode(nkDo, arg.info, body = arg,
-          params = nkFormalParams.newTree(p.emptyNode), name = p.emptyNode, pattern = p.emptyNode,
-          genericParams = p.emptyNode, pragmas = p.emptyNode, exceptions = p.emptyNode), {})
+      let
+        p = c.graph
+        lifted = c.semExpr(c, newProcNode(nkDo, arg.info,
+                                  name = p.emptyNode,
+                                  genericParams = p.emptyNode,
+                                  params = nkFormalParams.newTree(p.emptyNode),
+                                  pragmas = p.emptyNode,
+                                  exceptions = p.emptyNode,
+                                  body = arg,
+                                  pattern = p.emptyNode))
+
       if f.kind == tyBuiltInTypeClass:
         inc m.genericMatches
         put(m, f, lifted.typ)
+
       inc m.convMatches
       result = implicitConv(nkHiddenStdConv, f, lifted, m, c)
       return
+    else:
+      discard # keep processing below
+
     result = userConvMatch(c, m, f, a, arg)
+
     # check for a base type match, which supports varargs[T] without []
     # constructor in a call:
     if result == nil and f.kind == tyVarargs:
@@ -2196,7 +2361,8 @@ proc paramTypesMatchAux(m: var TCandidate, f, a: PType,
           m.baseTypeMatch = true
         else:
           result = userConvMatch(c, m, base(f), a, arg)
-          if result != nil: m.baseTypeMatch = true
+          if result != nil:
+            m.baseTypeMatch = true
 
 proc paramTypesMatch*(m: var TCandidate, f, a: PType,
                       arg: PNode): PNode =
@@ -2305,19 +2471,24 @@ proc prepareOperand(c: PContext; a: PNode): PNode =
 proc prepareNamedParam(a: PNode; c: PContext) =
   ## set the correct ident node, or nkError, in the 0th position for this
   ## named param
-  if a.isErrorLike: return
-  case a[0].kind
-  of nkIdent, nkError:
-    discard "nothing to do"
+  doAssert not a.isErrorLike, "named param is error like"
+
+  case a.kind
+  of nkExprEqExpr:
+    case a[0].kind
+    of nkIdent, nkError:
+      discard "nothing to do"
+    else:
+      let
+        info = a[0].info
+        (i, err) = considerQuotedIdent(c, a[0])
+      a[0] =
+        if err.isNil():
+          newIdentNode(i, info)   # xxx: going "backwards" to an ident, fishy
+        else:
+          err
   else:
-    let
-      info = a[0].info
-      (i, err) = considerQuotedIdent(c, a[0])
-    a[0] =
-      if err.isNil():
-        newIdentNode(i, info)
-      else:
-        err
+    c.config.internalError("named param must be exprEqExpr, got: " & $a.kind)
 
 
 proc arrayConstr(c: PContext, n: PNode): PType =
@@ -2341,15 +2512,25 @@ template isVarargsUntyped(x): untyped =
 proc findFirstArgBlock(m: var TCandidate, n: PNode): int =
   # see https://github.com/nim-lang/RFCs/issues/405
   result = int.high
-  for a2 in countdown(n.len-1, 0):
+  for a2 in countdown(n.len - 1, 0):
     # checking `nfBlockArg in n[a2].flags` wouldn't work inside templates
-    if n[a2].kind != nkStmtList: break
-    let formalLast = m.callee.n[m.callee.n.len - (n.len - a2)]
-    if formalLast.kind == nkSym and formalLast.sym.ast == nil:
-      result = a2
-    else: break
+    # xxx: ^^ why???
+    case n[a2].kind
+    of nkStmtList:
+      let formalLast = m.callee.n[m.callee.n.len - (n.len - a2)]
+
+      if formalLast.kind == nkSym and formalLast.sym.ast == nil:
+        result = a2
+      else:
+        break
+    else:
+      break
+
 
 proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
+  ## used to match a call `n` with a candidate `m`, noting matched formal
+  ## params in `marker` by position. `m` and `marker` are out parameters and
+  ## updated with the produced results.
 
   template noMatch() =
     c.mergeShadowScope #merge so that we don't have to resem for later overloads
@@ -2388,93 +2569,125 @@ proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
   m.call = newNodeIT(n.kind, n.info, m.callee.base)
   m.call.add n[0]
 
+  let firstArgBlock = findFirstArgBlock(m, n)
+
   var
-    a = 1 # iterates over the actual given arguments
+    a = 1
+      ## index to iterate over the actual given arguments
     f = if m.callee.kind != tyGenericBody: 1
-        else: 0 # iterates over formal parameters
-    arg: PNode # current prepared argument
+        else: 0
+      ## index to iterate over formal parameters
+    arg: PNode
+      ## current prepared argument
     formalLen = m.callee.n.len
-    formal = if formalLen > 1: m.callee.n[1].sym else: nil # current routine parameter
-    container: PNode = nil # constructed container
-  let firstArgBlock = findFirstArgBlock(m, n)
+    formal = if formalLen > 1: m.callee.n[1].sym else: nil
+      ## current routine parameter
+    container: PNode = nil
+      ## container (arg list, bracket, ...) to store intermediaries
+
   while a < n.len:
     c.openShadowScope
 
-    if a >= formalLen-1 and f < formalLen and m.callee.n[f].typ.isVarargsUntyped:
+    # untyped varargs
+    if a >= formalLen - 1 and              # last or finished passing args
+       f < formalLen and                   # still have more formal params
+       m.callee.n[f].typ.isVarargsUntyped: # current formal is varargs untped
+      
       formal = m.callee.n[f].sym
       incl(marker, formal.position)
 
-      if n[a].kind == nkHiddenStdConv:
+      case n[a].kind
+      of nkHiddenStdConv:
+        # if there is a conversion we, "steal" its container and pass it along
         doAssert n[a][0].kind == nkEmpty and
                  n[a][1].kind in {nkBracket, nkArgList}
-        # Steal the container and pass it along
+        # xxx: is reusing the converted call arg's container sound?
         setSon(m.call, formal.position + 1, n[a][1])
       else:
+        # make sure we have a container for the varargs
         if container.isNil:
           container = newNodeIT(nkArgList, n[a].info, arrayConstr(c, n.info))
           setSon(m.call, formal.position + 1, container)
         else:
           incrIndexType(container.typ)
+        
         container.add n[a]
-    elif n[a].kind == nkExprEqExpr:
+    elif n[a].kind == nkExprEqExpr:        # named params `foo(bar = "baz")`
       # named param
+
+      # assume it's wrong, then prove it correct
       m.error.firstMismatch.kind = kUnknownNamedParam
+      
       # check if m.callee has such a param:
       prepareNamedParam(n[a], c)
+      
       if n[a].kind == nkError or n[a][0].kind != nkIdent:
         localReport(c.config, n[a].info, reportAst(
           rsemExpectedIdentifier, n[a],
           str = "named parameter has to be an identifier"
         ))
-
         noMatch()
+      
       formal = getNamedParamFromList(m.callee.n, n[a][0].ident)
-      if formal == nil or formal.isError:
+      
+      if formal.isNil or formal.isError:
         # no error message!
         noMatch()
+      
       if containsOrIncl(marker, formal.position):
         m.error.firstMismatch.kind = kAlreadyGiven
         # already in namedParams, so no match
         # we used to produce 'errCannotBindXTwice' here but see
-        # bug #3836 of why that is not sound (other overload with
-        # different parameter names could match later on):
+        # bug https://github.com/nim-lang/nim/issues/3836 for why that is not
+        # sound (other overload with different parameter names could match
+        # later on)
+        #
+        # xxx: with nkError this is likely no longer an issue
         when false: localReport(n[a].info, errCannotBindXTwice, formal.name.s)
         noMatch()
+      
       m.baseTypeMatch = false
       m.typedescMatched = false
       n[a][1] = prepareOperand(c, formal.typ, n[a][1])
       n[a].typ = n[a][1].typ
       arg = paramTypesMatch(m, formal.typ, n[a].typ, n[a][1])
       m.error.firstMismatch.kind = kTypeMismatch
+      
       if arg == nil or arg.isErrorLike:
         noMatch()
-      elif n[a][1].isErrorLike:
+      elif n[a][1].isErrorLike: # named param's value is an error
         noMatchDueToError()
-      checkConstraint(n[a][1])
+      
+      checkConstraint(n[a][1])  # will update `m` with info
+      
       if m.baseTypeMatch:
         #assert(container == nil)
         container = newNodeIT(nkBracket, n[a].info, arrayConstr(c, arg))
         container.add arg
         setSon(m.call, formal.position + 1, container)
-        if f != formalLen - 1: container = nil
+        if f != formalLen - 1: # not the last formal param
+          container = nil      # xxx: is this more vararg stuff?
       else:
         setSon(m.call, formal.position + 1, arg)
+      
       inc f
-    else:
-      # unnamed param
+    else:                                  # unnamed param `foo("baz")`
       if f >= formalLen:
         # too many arguments?
         if tfVarargs in m.callee.flags:
           # is ok... but don't increment any counters...
           # we have no formal here to snoop at:
           n[a] = prepareOperand(c, n[a])
-          if skipTypes(n[a].typ, abstractVar-{tyTypeDesc}).kind==tyString:
+
+          case skipTypes(n[a].typ, abstractVar-{tyTypeDesc}).kind
+          of tyString:
+            # implicit conversion string -> cstring
             m.call.add implicitConv(nkHiddenStdConv,
-                  getSysType(c.graph, n[a].info, tyCstring),
-                  copyTree(n[a]), m, c)
+                                    getSysType(c.graph, n[a].info, tyCstring),
+                                    copyTree(n[a]), m, c)
           else:
             m.call.add copyTree(n[a])
-        elif formal != nil and formal.typ.kind == tyVarargs:
+        elif formal != nil and formal.typ.kind == tyVarargs: # extra varargs
           m.error.firstMismatch.kind = kTypeMismatch
           # beware of the side-effects in 'prepareOperand'! So only do it for
           # varargs matching. See tests/metatype/tstatic_overloading.
@@ -2482,13 +2695,16 @@ proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
           m.typedescMatched = false
           incl(marker, formal.position)
           n[a] = prepareOperand(c, formal.typ, n[a])
-          arg = paramTypesMatch(m, formal.typ, n[a].typ,
-                                    n[a])
-          if arg != nil and arg.kind != nkError and m.baseTypeMatch and container != nil:
+          arg = paramTypesMatch(m, formal.typ, n[a].typ, n[a])
+
+          if arg != nil and arg.kind != nkError and # valid argument
+             m.baseTypeMatch and                    # match type in `varargs[T]`
+             container != nil:                      # container must exist
+            
             container.add arg
             incrIndexType(container.typ)
             checkConstraint(n[a])
-          elif n[a].isErrorLike:
+          elif n[a].isErrorLike:                    # invalid operand
             noMatchDueToError()
           else:
             noMatch()
@@ -2496,50 +2712,66 @@ proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
           m.error.firstMismatch.kind = kExtraArg
           noMatch()
       else:
-        c.config.internalAssert(m.callee.n[f].kind == nkSym, n[a].info, "matches")
-        if a >= firstArgBlock: f = max(f, m.callee.n.len - (n.len - a))
+        c.config.internalAssert(m.callee.n[f].kind == nkSym, n[a].info,
+                                "matches")
+
+        if a >= firstArgBlock:
+          f = max(f, m.callee.n.len - (n.len - a))
+
         formal = m.callee.n[f].sym
         m.error.firstMismatch.kind = kTypeMismatch
+
+        # both positional and named argument for the same formal
         if containsOrIncl(marker, formal.position) and container.isNil:
           m.error.firstMismatch.kind = kPositionalAlreadyGiven
-          # positional param already in namedParams: (see above remark)
-          when false: localReport(n[a].info, errCannotBindXTwice, formal.name.s)
+          # positional param already in namedParams, see named param handling
+          # above for additional remarks about `errCannotBindXTwice`
+          #
+          # xxx: shouldn't be an issue with nkError
+          when false:
+            localReport(n[a].info, errCannotBindXTwice, formal.name.s)
           noMatch()
 
-        if formal.typ.isVarargsUntyped:
+        if formal.typ.isVarargsUntyped: # first untyped varargs param
           if container.isNil:
             container = newNodeIT(nkArgList, n[a].info, arrayConstr(c, n.info))
             setSon(m.call, formal.position + 1, container)
           else:
             incrIndexType(container.typ)
+
           container.add n[a]
-        else:
+        else:                           # additional varargs or other param
+          
+          # xxx: this code and the unnamed/varargs handling above are near
+          #      identical, should revise the overall logic and deduplicate
+          
           m.baseTypeMatch = false
           m.typedescMatched = false
           n[a] = prepareOperand(c, formal.typ, n[a])
-          arg = paramTypesMatch(m, formal.typ, n[a].typ,
-                                    n[a])
+          arg = paramTypesMatch(m, formal.typ, n[a].typ, n[a])
 
-          if arg == nil or arg.isErrorLike:
+          if arg == nil or arg.isErrorLike: # invalid arg
             noMatch()
-          elif n[a].isErrorLike:
+          elif n[a].isErrorLike:            # invalid operand
             noMatchDueToError()
-          if m.baseTypeMatch:
+
+          if m.baseTypeMatch: # var args
             assert formal.typ.kind == tyVarargs
-            #assert(container == nil)
+            
             if container.isNil:
               container = newNodeIT(nkBracket, n[a].info, arrayConstr(c, arg))
               container.typ.flags.incl tfVarargs
             else:
               incrIndexType(container.typ)
+            
             container.add arg
             setSon(m.call, formal.position + 1,
                    implicitConv(nkHiddenStdConv, formal.typ, container, m, c))
-            #if f != formalLen - 1: container = nil
 
-            # pick the formal from the end, so that 'x, y, varargs, z' works:
+            # pick the formal from the end, so a regular param can follow a
+            # varargs: 'foo(x: int, y: varargs[typed], blk: untyped): typed'
             f = max(f, formalLen - n.len + a + 1)
-          elif formal.typ.kind != tyVarargs or container == nil:
+          elif formal.typ.kind != tyVarargs or container == nil: # regular arg
             setSon(m.call, formal.position + 1, arg)
             inc f
             container = nil
@@ -2547,8 +2779,7 @@ proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
             # we end up here if the argument can be converted into the varargs
             # formal (e.g. seq[T] -> varargs[T]) but we have already instantiated
             # a container
-            #assert arg.kind == nkHiddenStdConv # for 'nim check'
-            # this assertion can be off
+
             localReport(c.config, n[a].info,
               SemReport(
                 kind: rsemCannotConvertTypes,
@@ -2556,14 +2787,18 @@ proc matchesAux(c: PContext, n: PNode, m: var TCandidate, marker: var IntSet) =
                   formal = formal.typ, actual = n[a].typ)]))
 
             noMatch()
+
         checkConstraint(n[a])
 
-    if m.state == csMatch and not (m.calleeSym != nil and m.calleeSym.kind in {skTemplate, skMacro}):
+    if m.state == csMatch and
+       not (m.calleeSym != nil and m.calleeSym.kind in {skTemplate, skMacro}):
       c.mergeShadowScope
     else:
       c.closeShadowScope
 
     inc a
+
+  # xxx: what???
   # for some edge cases (see tdont_return_unowned_from_owned test case)
   m.error.firstMismatch.pos = a
   m.error.firstMismatch.formal = formal
@@ -2581,28 +2816,42 @@ proc partialMatch*(c: PContext, n: PNode, m: var TCandidate) =
 
 proc matches*(c: PContext, n: PNode, m: var TCandidate) =
   addInNimDebugUtils(c.config, "matches", n, m)
+
   if m.magic in {mArrGet, mArrPut}:
     m.state = csMatch
     m.call = n
+
     # Note the following doesn't work as it would produce ambiguities.
-    # Instead we patch system.nim, see bug #8049.
+    # We hack system.nim instead: https://github.com/nim-lang/nim/issues/8049.
+    # xxx: shouldn't this be a generic match and not an exact one, then?
     when false:
       inc m.genericMatches
       inc m.exactMatches
+
     return
+  
   var marker = initIntSet()
   matchesAux(c, n, m, marker)
-  if m.state == csNoMatch: return
+
+  if m.state == csNoMatch:
+    return
+
   # check that every formal parameter got a value:
   for f in 1..<m.callee.n.len:
     let formal = m.callee.n[f].sym
     if not containsOrIncl(marker, formal.position):
-      if formal.ast == nil:
+      if formal.ast == nil:            # no default values
         if formal.typ.kind == tyVarargs:
           # For consistency with what happens in `matchesAux` select the
           # container node kind accordingly
-          let cnKind = if formal.typ.isVarargsUntyped: nkArgList else: nkBracket
-          var container = newNodeIT(cnKind, n.info, arrayConstr(c, n.info))
+          let
+            cnKind =
+              if formal.typ.isVarargsUntyped:
+                nkArgList
+              else:
+                nkBracket
+            container = newNodeIT(cnKind, n.info, arrayConstr(c, n.info))
+          
           setSon(m.call, formal.position + 1,
                  implicitConv(nkHiddenStdConv, formal.typ, container, m, c))
         else:
@@ -2611,32 +2860,44 @@ proc matches*(c: PContext, n: PNode, m: var TCandidate) =
           m.error.firstMismatch.kind = kMissingParam
           m.error.firstMismatch.formal = formal
           break
-      else:
-        if formal.ast.kind == nkEmpty:
-          # The default param value is set to empty in `instantiateProcType`
-          # when the type of the default expression doesn't match the type
-          # of the instantiated proc param:
-          c.config.localReport(reportSym(
-            rsemIncompatibleDefaultExpr, formal))
+      else:                            # handle default values
+        # given: `proc foo(x: T = 0.0)`, then call `foo()` should work
+
+        let defaultValue =
+          case formal.ast.kind
+          of nkEmpty:
+            # The default param value is set to empty in `instantiateProcType`
+            # when the type of the default expression doesn't match the type
+            # of the instantiated proc param:
+            c.config.newError(m.callee.n[f],
+                              reportSym(rsemIncompatibleDefaultExpr, formal))
+          of nkNilLit:
+            implicitConv(nkHiddenStdConv, formal.typ, copyTree(formal.ast), m, c)
+          else:
+            copyTree(formal.ast)
+
+        if defaultValue.isError:
+          # xxx: change this to propagate
+          c.config.localReport(defaultValue)
 
         if nfDefaultRefsParam in formal.ast.flags:
           m.call.flags.incl nfDefaultRefsParam
-        var defaultValue = copyTree(formal.ast)
-        if defaultValue.kind == nkNilLit:
-          defaultValue = implicitConv(nkHiddenStdConv, formal.typ, defaultValue, m, c)
-        # proc foo(x: T = 0.0)
-        # foo()
+
         if {tfImplicitTypeParam, tfGenericTypeParam} * formal.typ.flags != {}:
           let existing = PType(idTableGet(m.bindings, formal.typ))
+
           if existing == nil or existing.kind == tyTypeDesc:
-            # see bug #11600:
+            # see bug https://github.com/nim-lang/nim/issues/11600:
             put(m, formal.typ, defaultValue.typ)
+        
         defaultValue.flags.incl nfDefaultParam
         setSon(m.call, formal.position + 1, defaultValue)
+  
   # forget all inferred types if the overload matching failed
   if m.state == csNoMatch:
     for t in m.inferredTypes:
-      if t.len > 1: t.sons.setLen 1
+      if t.len > 1:
+        t.sons.setLen 1
 
 proc argtypeMatches*(c: PContext, f, a: PType, fromHlo = false): bool =
   var m = newCandidate(c, f)