clearer description of memory()

compiler/res/prog8lib/cx16/gfx2.p8

@@ -334,7 +334,7 @@ _done
             return
         }
 
-        ; TODO rewrite the rest in optimized assembly
+        ; TODO rewrite the rest in optimized assembly (or reuse GRAPH_draw_line if we can get the FB replacement vector layer working)
         word @zp d = 0
         ubyte positive_ix = true
         if dx < 0 {

docs/source/programming.rst

@@ -840,12 +840,15 @@ swap(x, y)
     Swap the values of numerical variables (or memory locations) x and y in a fast way.
 
 memory(name, size)
-    Statically allocates a fixed portion of memory of the given size in bytes, and returns its address.
-    Slabs are considered identical if their name and size are the same.
-    This can be used to allocate parts of the memory where a normal byte array would
-    not suffice for instance if you need more than 256 bytes, and/or don't want to work
-    with fixed memory addresses for buffers.
-    The portion of memory cannot be used as an array, you only have the address of the first byte.
+    Returns the address of the first location of a statically "reserved" block of memory of the given size in bytes,
+    with the given name. Requesting the address of such a named memory block again later with
+    the same name, will result in the same address as before.
+    When reusing blocks in that way, it is required that the size argument is the same,
+    otherwise you'll get a compilation error.
+    This routine can be used to "reserve" parts of the memory where a normal byte array variable would
+    not suffice; for instance if you need more than 256 consecutive bytes.
+    The return value is just a simple uword address so it cannot be used as an array in your program.
+    You can only treat it as a pointer or use it in inline assembly.
 
 
 Library routines

docs/source/todo.rst

@@ -2,7 +2,6 @@
 TODO
 ====
 
-- (github issue:) replace memory() function by some sort of declaration?
 - use (zp) addressing mode on 65c02 specific code rather than ldy#0 / lda (zp),y
 - optimize pointer access code @(pointer)? use a subroutine? macro?  65c02 vs 6502?
 - can we get rid of the --longOptionName command line options and only keep the short versions? https://github.com/Kotlin/kotlinx-cli/issues/50

examples/test.p8

@@ -1,41 +1,20 @@
-%import test_stack
 %import textio
-%import diskio
 %import string
 %zeropage basicsafe
 %option no_sysinit
 
 main {
 
-    sub start() {
-        ubyte[40] input_line
 
-        if diskio.f_open(8, "romdis.asm") {
-            uword line=0
-            repeat 5 {
-                ubyte length = diskio.f_readline(input_line)
-                if length {
-                    line++
-                    txt.print_uw(line)
-                    txt.chrout(':')
-                    txt.print_ub(length)
-                    txt.print(":[")
-                    ubyte xx
-                    for xx in 0 to length-1 {
-                        txt.print_ubhex(input_line[xx], 1)
-                        txt.chrout(' ')
-                    }
-                    ; txt.print(&input_line)
-                    txt.print("]\n")
-                    ; textparse.process_line()
-                    if c64.READST()         ; TODO also check STOP key
-                        break
-                } else
-                    break
-            }
-            diskio.f_close()
-        }
+    sub start() {
+        txt.print_uwhex(memory("a", 100), 1)
+        txt.nl()
+        txt.print_uwhex(memory("a", 200), 1)
+        txt.nl()
+        txt.print_uwhex(memory("a", 200), 1)
+        txt.nl()
+        txt.print_uwhex(memory("b", 200), 1)
+        txt.nl()
     }
 
-
 }