Friendlier error message with solution (#19880)

* Add helpful suggestion, should always apply

* mention var param limitation in async docs

* Update compiler/lambdalifting.nim

whoops thanks

Co-authored-by: flywind <43030857+xflywind@users.noreply.github.com>

Co-authored-by: flywind <43030857+xflywind@users.noreply.github.com>

compiler/lambdalifting.nim

@@ -288,7 +288,8 @@ proc markAsClosure(g: ModuleGraph; owner: PSym; n: PNode) =
   if illegalCapture(s):
     localError(g.config, n.info,
       ("'$1' is of type <$2> which cannot be captured as it would violate memory" &
-       " safety, declared here: $3; using '-d:nimNoLentIterators' helps in some cases") %
+       " safety, declared here: $3; using '-d:nimNoLentIterators' helps in some cases." &
+       " Consider using a <ref $2> which can be captured.") %
       [s.name.s, typeToString(s.typ), g.config$s.info])
   elif not (owner.typ.callConv == ccClosure or owner.typ.callConv == ccNimCall and tfExplicitCallConv notin owner.typ.flags):
     localError(g.config, n.info, "illegal capture '$1' because '$2' has the calling convention: <$3>" %

lib/pure/asyncdispatch.nim

@@ -98,6 +98,10 @@
 ## `await`. The following section shows different ways that you can handle
 ## exceptions in async procs.
 ##
+## .. caution::
+##     Procedures marked {.async.} do not support mutable parameters such
+##     as `var int`. References such as `ref int` should be used instead.
+##
 ## Handling Exceptions
 ## -------------------
 ##
@@ -192,6 +196,7 @@
 ## ================
 ##
 ## * The effect system (`raises: []`) does not work with async procedures.
+## * Mutable parameters are not supported by async procedures.
 ##
 ##
 ## Multiple async backend support