chore: document VariableHandler

Author: agurtovoy

source/common/expressions/term/variable.asm

@@ -1,26 +1,36 @@
-; ************************************************************************************************
-; ************************************************************************************************
-;
-;		Name:		variable.asm
-;		Purpose:	Variable handler
-;		Created:	30th September 2022
-;		Reviewed: 	28th November 2022
-;		Author:		Paul Robson (paul@robsons.org.uk)
-;
-; ************************************************************************************************
-; ************************************************************************************************
+;;
+; Variable term parsing and array access logic
+;;
 
 		.section code
 
-; ************************************************************************************************
+;;
+; Parse a variable term into a number-stack reference.
 ;
-;									Variable handler
+; Reads the encoded variable reference at the current token position, resolves
+; the variable record address in `VariableSpace`, and constructs a reference
+; value in the current number-stack slot. Scalar variables return immediately as
+; references to their stored data; array references dispatch to the array
+; access logic, which also handles function-call syntax for procedure arrays.
 ;
-; ************************************************************************************************
+; \in X         Number-stack slot to receive the variable reference.
+; \in Y         Parsing position at the encoded variable token.
+; \out Y        Advanced past the encoded variable reference.
+; \out NSMantissa[0..3],x  Reference payload pointing at the variable data.
+; \out NSExponent,x        Cleared for the constructed reference.
+; \out NSStatus,x          Variable base type with `NSBIsReference` set; array
+;                          variables also retain the array flag.
+; \sideeffects  - Uses `zTemp0` as a pointer to the variable record.
+;               - Reads the variable type byte from the record metadata.
+;               - May dispatch to array indexing or `FunctionCall` handling
+;                 for array/procedure references.
+;               - Modifies registers `A` and `Y`.
+; \see          FunctionCall, Evaluate8BitInteger, CheckRightBracket
+;;
 
 VariableHandler:
 		.cget 								; copy variable address to zTemp0
-		clc 								
+		clc
 		adc 	#((VariableSpace >> 8) - $40) & $FF
 		sta 	zTemp0+1
 		iny
@@ -87,7 +97,7 @@ _VHNoSecondIndex:
 		;
 		;		So at this point S[X] refers to the array record S[X+1] the 1st index, and S[X+2] the second
 		;		Status[X+2] is $FF if there was only one array index, $00 if there were two.
-		;		
+		;
 		; -----------------------------------------------------------------------------------------------------
 		;
 		;		So first check if the number of indices match
@@ -118,15 +128,15 @@ _VHHas2Mask: 								; so we are now 0 if there is 1 index, and $FF if there is
 		;
 		;		Second index
 		;
-		ldy 	#3 			 				; check the 2nd size >= 2nd index				
+		ldy 	#3 			 				; check the 2nd size >= 2nd index
 		lda 	(zaTemp),y
 		cmp 	NSMantissa0+2,x
 		bcc 	_VHBadIndex
 		;
 		;		First index
 		;
 _VHCheckFirstIndex:
-		ldy 	#2 			 				; check the 2nd size >= 2nd index				
+		ldy 	#2 			 				; check the 2nd size >= 2nd index
 		lda 	(zaTemp),y
 		cmp 	NSMantissa0+1,x
 		bcc 	_VHBadIndex
@@ -146,7 +156,7 @@ _VHCheckFirstIndex:
 		ldy 	#2 							; get 1st size in A
 		lda 	(zaTemp),y
 		inc 	a 							; add 1 for zero base
-		plx 								
+		plx
 		jsr 	Multiply8x8 				; calculate -> Z0
 		plx
 _VHNoMultiply:
@@ -161,7 +171,7 @@ _VHNoMultiply:
 		adc 	#0
 		sta 	zTemp0+1
 		;
-		;		Get the type (from Status,0) and use it to scale up 
+		;		Get the type (from Status,0) and use it to scale up
 		;
 		lda 	NSStatus,x
 		jsr 	ScaleByBaseType
@@ -187,18 +197,3 @@ _VHBadArray:
 		.error_arraydec
 
 		.send code
-
-; ************************************************************************************************
-;
-;									Changes and Updates
-;
-; ************************************************************************************************
-;
-;		Date			Notes
-;		==== 			=====
-;		06/12/22 		Added array not declared error.
-;		06/12/22 		At the check of indices match, around line 87, the copy into zaTemp was
-;						done *before* zaTemp was initialised,so it checked the last assigned value.
-;						Swapped round. Would only be picked up with uninitialised arrays.
-;
-; ************************************************************************************************