add note about unspecified order of evaluation of expressions and subroutine call arguments

docs/docs.iml

@@ -5,7 +5,7 @@
     <content url="file://$MODULE_DIR$">
       <excludeFolder url="file://$MODULE_DIR$/build" />
     </content>
-    <orderEntry type="jdk" jdkName="Python 3.9 (py3)" jdkType="Python SDK" />
+    <orderEntry type="jdk" jdkName="Python 3.10 (py3)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
 </module>

docs/source/programming.rst

@@ -599,9 +599,15 @@ You can also reference idendifiers defined elsewhere in your code.
 
 Read the :ref:`syntaxreference` chapter for all details on the available operators and kinds of expressions you can write.
 
+.. note::
+    **Order of evaluation:**
+
+    The order of evaluation of expression operands is *unspecified* and should not be relied upon.
+    There is no guarantee of a left-to-right or right-to-left evaluation. But don't confuse this with
+    operator precedence order (multiplication comes before addition etcetera).
 
 .. attention::
-    **Floating points used in expressions:**
+    **Floating point values used in expressions:**
 
     When a floating point value is used in a calculation, the result will be a floating point, and byte or word values
     will be automatically converted into floats in this case. The compiler will issue a warning though when this happens, because floating
@@ -679,6 +685,12 @@ The arguments in parentheses after the function name, should match the parameter
 If you want to ignore a return value of a subroutine, you should prefix the call with the ``void`` keyword.
 Otherwise the compiler will issue a warning about discarding a result value.
 
+.. note::
+    **Order of evaluation:**
+
+    The order of evaluation of arguments is *unspecified* and should not be relied upon.
+    There is no guarantee of a left-to-right or right-to-left evaluation of the call arguments.
+
 .. caution::
     Note that due to the way parameters are processed by the compiler,
     subroutines are *non-reentrant*. This means you cannot create recursive calls.

docs/source/technical.rst

@@ -64,10 +64,11 @@ regular subroutines
 - subroutine parameters are just variables scoped to the subroutine.
 - the arguments passed in a call are evaluated (using the eval-stack if needed) and then
   copied into those variables.
-  This sometimes can seem inefficient but it's required to allow subroutines to work locally
+  Using variables for this sometimes can seem inefficient but it's required to allow subroutines to work locally
   with their parameters and allow them to modify them as required, without changing the
   variables used in the call's arguments.  If you want to get rid of this overhead you'll
   have to make an ``asmsub`` routine in assembly instead.
+- the order of evaluation of subroutine call arguments *is unspecified* and should not be relied upon.
 - the return value is passed back to the caller via cpu register(s):
   Byte values will be put in ``A`` .
   Word values will be put in ``A`` + ``Y`` register pair.

docs/source/todo.rst

@@ -3,7 +3,7 @@ TODO
 
 For next compiler release (7.7)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-...tbd
+- add unit tests for correctly parsing the "in" operator
 
 
 Need help with
@@ -22,6 +22,7 @@ Blocked by an official Commander-x16 r39 release
 Future Things and Ideas
 ^^^^^^^^^^^^^^^^^^^^^^^
 - pipe operator ``|>``
+- can we promise a left-to-right function call argument evaluation? without sacrificing performance
 - make it possible to use cpu opcodes such as 'nop' as variable names by prefixing all asm vars with something such as ``v_``
   then we can get rid of the instruction lists in the machinedefinitions as well?
 - fix the asm-labels problem (github issue #62)