doc tweaks, explain str a bit more

docs/source/programming.rst

@@ -289,7 +289,7 @@ Here are some examples of arrays::
     byte[]  array = [1, 2, 3, 4]      ; initialize the array, size taken from value
     ubyte[99] array = 255             ; initialize array with 99 times 255 [255, 255, 255, 255, ...]
     byte[] array = 100 to 199         ; initialize array with [100, 101, ..., 198, 199]
-    str[] names = ["ally", "pete"]    ; array of string pointers/addresses (equivalent to uword)
+    str[] names = ["ally", "pete"]    ; array of string pointers/addresses (equivalent to array of uwords)
     uword[] others = [names, array]   ; array of pointers/addresses to other arrays
 
     value = array[3]            ; the fourth value in the array (index is 0-based)
@@ -349,7 +349,7 @@ Note that the maximum length of a split word array is 256! (regular word arrays
 Strings
 ^^^^^^^
 
-Strings are a sequence of characters enclosed in ``"`` quotes. The length is limited to 255 characters.
+Strings are a sequence of characters enclosed in double quotes. The length is limited to 255 characters.
 They're stored and treated much the same as a byte array,
 but they have some special properties because they are considered to be *text*.
 Strings (without encoding prefix) will be encoded (translated from ASCII/UTF-8) into bytes via the
@@ -407,6 +407,11 @@ for a character in such strings (one that stops at the first 0 byte)
     For regular assignments you still need to use an explicit ``&`` (address-of) to take
     the address of the string or array.
 
+.. hint::
+    You can declare parameters and return values of subroutines as ``str``,
+    but in this case that is equivalent to declaring them as ``uword`` (because
+    in this case, the address of the string is passed as argument or returned as value).
+
 .. note:: Strings and their (im)mutability
 
     *String literals outside of a string variable's initialization value*,

docs/source/technical.rst

@@ -52,14 +52,13 @@ Subroutine Calling Convention
 
 Calling a subroutine requires three steps:
 
-#. preparing the arguments (if any) and passing them to the routine
-#. calling the routine
+#. preparing the arguments (if any) and passing them to the routine.
+   Numeric types are passed by value (bytes, words, booleans, floats),
+   but array types and strings are passed by reference which means as ``uword`` being a pointer to their address in memory.
+#. calling the subroutine
 #. preparing the return value (if any) and returning that from the call.
 
 
-Calling the routine is just a simple JSR instruction, but the other two work like this:
-
-
 ``asmsub`` routines
 ^^^^^^^^^^^^^^^^^^^
 

docs/source/todo.rst

@@ -2,10 +2,6 @@
 TODO
 ====
 
-- merge branch optimize-st  for some optimizations regarding SymbolTable use
-
-- fix that pesky unit test that puts temp files in the compiler directory
-
 - [on branch: call-pointers] allow calling a subroutine via a pointer variable (indirect JSR, optimized form of callfar())
    modify programs (shell, paint) that now use callfar
 
@@ -18,7 +14,7 @@ Future Things and Ideas
 ^^^^^^^^^^^^^^^^^^^^^^^
 Compiler:
 
-- What happens when subs return a boolean not in A, but in Carry flag?
+- (after shortcircuit is in:) What happens when we make all subs return a boolean not as ubyte in A, but in the cpu's Carry flag?
 - What happens when we keep the BOOL type around until in codegen? (so, get rid of Boolean->ubyte and boolean remover)
 - Multidimensional arrays and chained indexing, purely as syntactic sugar over regular arrays.
 - make a form of "manual generics" possible like: varsub routine(T arg)->T  where T is expanded to a specific type
@@ -34,11 +30,6 @@ Compiler:
     - OR.... make all this more generic and use some %segment option to create real segments for 64tass?
     - (need separate step in codegen and IR to write the "golden" variables)
 
-- [on branch: no-vardecls]
-    remove astNode from StNode in the symboltable
-    remove IPtVariable and the 3 derived types (var, constant, memmapped) in the codegen ast
-    remove VarDecls in compiler ast
-
 - do we need (array)variable alignment tag instead of block alignment tag? You want to align the data, not the code in the block?
 - ir: getting it in shape for code generation
 - ir: related to the one above: block alignment doesn't translate well to variables in the block (the actual stuff that needs to be aligned in memory)  but: need variable alignment tag instead of block alignment tag, really
@@ -92,5 +83,7 @@ What if we were to re-introduce Structs in prog8? Some thoughts:
 Other language/syntax features to think about
 ---------------------------------------------
 
+- add (rom/ram)bank support to romsub.   A call will then automatically switch banks, use callfar and something else when in banked ram.
+  challenges: how to not make this too X16 specific? How does the compiler know what bank to switch (ram/rom)?
 - chained comparisons   `10<x<20` ,   `x==y==z`   (desugars to  `10<x and x<20`,   `x==y and y==z`) BUT this changes the semantics of what it is right now ! (x==(y==z) --> x==true)
 - negative array index to refer to an element from the end of the array.  Python `[-1]` or Raku syntax `[\*-1]`  , `[\*/2]` .... \*=size of the array