doc: Extend documentation

Extend the paragraph "Pitfalls" in the documentation of "Compiler" by
problems caused by returning values from the stack.

doc/manual/compiler.rst

@@ -79,6 +79,43 @@ interpreter.
 
 Empty lists do not have valid list element types, so they cannot be used in the kernel.
 
+In kernels, lifetime of allocated values (e.g. lists or numpy arrays) might not be correctly
+tracked across function calls (see `#1497 <https://github.com/m-labs/artiq/issues/1497>`_,
+`#1677 <https://github.com/m-labs/artiq/issues/1677>`_) like in this example ::
+
+    @kernel
+    def func(a):
+        return a
+
+    class ProblemReturn1(EnvExperiment):
+        def build(self):
+            self.setattr_device("core")
+
+        @kernel
+        def run(self):
+            # results in memory corruption
+            return func([1, 2, 3])
+or if the return value is obfuscated by an if-statement like here: ::
+
+    class ProblemReturn2(EnvExperiment):
+        def build(self):
+            self.setattr_device("core")
+
+        @kernel
+        def meth(self):
+            # if statement for obfuscation
+            if self.core.get_rtio_counter_mu() % 2:
+                return np.array([1,2,3])
+            else:
+                return np.array([4,5,6])
+
+        @kernel
+        def run(self):
+            # also results in memory corrption
+            return self.meth()
+
+This results in memory corruption at runtime.
+
 Asynchronous RPCs
 -----------------