From c9a61895ad11da63357dd84d7f1ab0b899077e50 Mon Sep 17 00:00:00 2001
From: narimiran <narimiran@disroot.org>
Date: Sat, 8 Feb 2020 10:43:48 +0100
Subject: [PATCH] fixes #3339 by documenting the limitations of case-statement

---
 doc/manual.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/manual.rst b/doc/manual.rst
index 55b14f83b020..2f5673684448 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -2843,6 +2843,35 @@ expanded into a list of its elements:
     of '0'..'9': echo "a number"
     else: echo "other"
 
+The ``case`` statement doesn't produce an l-value, so the following example
+won't work:
+
+.. code-block:: nim
+  type
+    Foo = ref object
+      x: seq[string]
+
+  proc get_x(x: Foo): var seq[string] =
+    # doesn't work
+    case true
+    of true:
+      x.x
+    else:
+      x.x
+
+  var foo = Foo(x: @[])
+  foo.get_x().add("asd")
+
+This can be fixed by explicitly using ``return``:
+
+.. code-block:: nim
+  proc get_x(x: Foo): var seq[string] =
+    case true
+    of true:
+      return x.x
+    else:
+      return x.x
+
 
 When statement
 --------------