Improve comments

Co-authored-by: Saem Ghani <[email protected]>

compiler/ast/trees.nim

@@ -46,10 +46,10 @@ proc sameFloatIgnoreNan(a, b: BiggestFloat): bool {.inline.} =
 
 template makeTreeEquivalenceProc*(
   name, relaxedKindCheck, symCheck, floatCheck, typeCheck, commentCheck) {.dirty.} =
-  # Defines a tree equivalence checking procedure.
-  # This skeleton is shared between all recursive
-  # PNode equivalence checks in the compiler code base
-  # It might be possible to unify more of them with each other.
+  ## Defines a tree equivalence checking procedure.
+  ## This skeleton is shared between all recursive
+  ## `PNode` equivalence checks in the compiler code base
+  ## It might be possible to unify more of them with each other.
   proc name(a, b: PNode): bool =
     result = false
     if a == b:
@@ -63,8 +63,8 @@ template makeTreeEquivalenceProc*(
       of nkIntLiterals:     result = a.intVal == b.intVal
       of nkFloatLiterals:   result = floatCheck
         # XXX: Using float equality, even if partially tamed through
-        # sameFloatIgnoreNan, causes inconsistencies due to it lacking
-        # the substition and reflexivity property.
+        #      sameFloatIgnoreNan, causes inconsistencies due to it
+        #      lacking the substition and reflexivity property.
       of nkStrLiterals:     result = a.strVal == b.strVal
       of nkType:            result = typeCheck
       of nkCommentStmt:     result = commentCheck

compiler/ast/types.nim

@@ -652,7 +652,10 @@ proc sameTypeOrNil*(a, b: PType, flags: TTypeCmpFlags = {}): bool =
     else: result = sameType(a, b, flags)
 
 proc equalParam(a, b: PSym): TParamsEquality =
-  # This is not commutative!
+  ## Returns wether parameters `a` and `b` are considered equal.
+  ## Note that this operation is not commutative, so when comparing
+  ## a forward declaration to an implementation, ensure `a` is the
+  ## param from the forward declaration.
   if sameTypeOrNil(a.typ, b.typ, {ExactTypeDescValues}) and
       exprStructuralEquivalent(a.constraint, b.constraint):
     if a.ast == b.ast: