From 6ebebe294ef0df78a5e69c264a362dd0fef4f710 Mon Sep 17 00:00:00 2001
From: n loewen <nick@nloewen.com>
Date: Thu, 3 Aug 2023 16:42:19 +0100
Subject: [PATCH] Add JSdoc annotatinos

---
 assembler.js | 11 +++++++----
 display.js   |  8 ++++++++
 simulator.js | 23 ++++++++++++++++++++---
 3 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/assembler.js b/assembler.js
index 72a8c78..801634d 100644
--- a/assembler.js
+++ b/assembler.js
@@ -27,8 +27,11 @@ const mnemonics2opcodes = {
   nop: { direct: 15, indirect: 15 },
 };
 
-function decodeInstructions(str) {
-  let lines = str.split(/\n/); // returns an array of lines
+/**
+ * @param {String} line - One line of assembly to decode
+ **/
+function decodeInstructions(line) {
+  let lines = line.split(/\n/); // returns an array of lines
 
   let machineCode = new Array(INITIAL_IP_ADDRESS).fill(0);
   machineCode[0] = POINTER_TO_START_OF_DISPLAY_MEM;
@@ -155,7 +158,7 @@ function decodeInstructions(str) {
     }
 
     // DECODE!
-    op = mnemonics2opcodes[opName][addressingMode];
+    const op = mnemonics2opcodes[opName][addressingMode];
 
     machineCode.push(op);
     machineCode.push(arg_num);
@@ -166,7 +169,7 @@ function decodeInstructions(str) {
 
   dbg(1, '');
   dbgGroup(1, 'Memory before filling in label constants');
-  dbgExec(1, () => logMemory(machineCode));
+  dbgExec(1, () => logMemory(new Uint8Array(machineCode)));
   dbgGroupEnd(1, 'Memory before filling in label constants');
 
   // Backfill label references
diff --git a/display.js b/display.js
index 94eb55b..9fe6303 100644
--- a/display.js
+++ b/display.js
@@ -1,6 +1,10 @@
 const { POINTER_TO_START_OF_DISPLAY_MEM } = require('./machine.config');
 const { num2hex } = require('./logging.js');
 
+/**
+ * Print the contents of display memory as hex number
+ * @param {Uint8Array} mem - CPU memory
+ **/
 const printDisplay = (mem) => {
   const disp = mem[POINTER_TO_START_OF_DISPLAY_MEM];
   for (let i = disp; i < disp + 16; i += 4) {
@@ -8,6 +12,10 @@ const printDisplay = (mem) => {
   }
 }
 
+/**
+ * Print the contents of display memory using black and white emoji circles
+ * @param {Uint8Array} mem - CPU memory
+ **/
 const prettyPrintDisplay = (mem) => {
   const disp = mem[POINTER_TO_START_OF_DISPLAY_MEM];
   const num2pic = (n) => n > 0 ? '⚫' : '⚪';
diff --git a/simulator.js b/simulator.js
index 10011dc..c3c0546 100644
--- a/simulator.js
+++ b/simulator.js
@@ -9,10 +9,13 @@ const CPU = {
   CF: 0,
   Acc: 0,
   memory: null,
-  loadMemory: (data) => { // data: Uint8Array
-    if (data.length > 256) { throw new Error("Out of memory error (program too long)"); }
-    CPU.memory = data;
+
+  /** @param {Uint8Array} data */
+  loadMemory: (data) => {
+      if (data.length > 256) { throw new Error("Out of memory error (program too long)"); }
+      CPU.memory = data;
   },
+
   currentInstruction: {
     opcode: null,
     argument: null,
@@ -173,11 +176,18 @@ const opcodes2mnemonics = {
   15: (arg) => Instructions.no_op(),
 };
 
+/**
+ * Load code into memory and set CPU state to "running"
+ * @param {Uint8Array} code - Machine code to load
+ **/
 function startCPU(code) {
   CPU.loadMemory(code);
   CPU.running = true;
 }
 
+/**
+ * Execute just the next instruction in memory
+ **/
 function stepCPU() {
   CPU.currentInstruction.opcode = CPU.memory[CPU.IP];
   CPU.currentInstruction.argument = CPU.memory[CPU.IP+1];
@@ -185,6 +195,10 @@ function stepCPU() {
   executeInstruction(CPU.currentInstruction.argument);
 }
 
+/**
+ * @param {Uint8Array} code - Machine code to run
+ * @param {Boolean} [debug] - Enable/disable debugging printouts
+ **/
 exports.runProgram = async (code, debug = false) => {
   startCPU(code);
   let step = 0;
@@ -201,6 +215,9 @@ exports.runProgram = async (code, debug = false) => {
 
 // FUNCTIONS THAT PULL INFO FROM STATE TO DISPLAY
 
+/**
+ * @param {Boolean} [debug] - Enable/disable debugging printouts
+ **/
 async function logCPUState(debug = false) {
   console.group(`Step`);
     if (!debug) console.clear();