From 12d0e5403acb03070e0bea580d7de7f4413be31e Mon Sep 17 00:00:00 2001
From: Peter Evans <pevans@activecampaign.com>
Date: Wed, 6 Dec 2017 17:03:37 -0600
Subject: [PATCH] Add documentation for the arith instructions

---
 src/mos6502.arith.c | 49 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/src/mos6502.arith.c b/src/mos6502.arith.c
index 72744d7..b07a638 100644
--- a/src/mos6502.arith.c
+++ b/src/mos6502.arith.c
@@ -5,27 +5,53 @@
 #include "mos6502.h"
 #include "mos6502.enums.h"
 
+/*
+ * The adc instruction will add a number to the accumulator, "with
+ * carry". If the carry bit is set, we will add 1 to the accumulator as
+ * an after-effect.
+ */
 DEFINE_INST(adc)
 {
     CARRY_BIT();
     cpu->A += oper + carry;
 }
 
+/*
+ * The cmp instruction will consider the difference of the accumulator
+ * minus the operand. It will then set the zero, negative, or carry bits
+ * based upon that difference. _The accumulator is neither modified nor
+ * harmed by this operation._ (We have trained experts on the set to
+ * monitor the health of the accumulator, whom we've named George.)
+ */
 DEFINE_INST(cmp)
 {
     mos6502_modify_status(cpu, ZERO | NEGATIVE | CARRY, cpu->A - oper);
 }
 
+/*
+ * This instruction is functionally identical to CMP, with the exception
+ * that it considers the X register rather than the accumulator.
+ */
 DEFINE_INST(cpx)
 {
     mos6502_modify_status(cpu, ZERO | NEGATIVE | CARRY, cpu->X - oper);
 }
 
+/*
+ * Again, this is a variant of the CMP instruction, except that it works
+ * with the Y register.
+ */
 DEFINE_INST(cpy)
 {
     mos6502_modify_status(cpu, ZERO | NEGATIVE | CARRY, cpu->Y - oper);
 }
 
+/*
+ * Here we will decrement the value at the effective address in memory
+ * by 1. The DEC instruction is _unable_ to decrement the accumulator,
+ * which was a tiny oversight in the original build of the 6502.
+ * (Whoopsie!)
+ */
 DEFINE_INST(dec) 
 {
     if (cpu->last_addr) {
@@ -33,16 +59,27 @@ DEFINE_INST(dec)
     }
 }
 
+/*
+ * In contrast, this does directly decrement the X register.
+ */
 DEFINE_INST(dex)
 {
     cpu->X--;
 }
 
+/*
+ * And, again, here we decrement the Y register.
+ */
 DEFINE_INST(dey)
 {
     cpu->Y--;
 }
 
+/*
+ * The INC instruction is basically the same as the DEC one. It, also,
+ * can only work with an address in memory, and it increments the value
+ * by 1.
+ */
 DEFINE_INST(inc)
 {
     if (cpu->last_addr) {
@@ -50,16 +87,28 @@ DEFINE_INST(inc)
     }
 }
 
+/*
+ * See DEX.
+ */
 DEFINE_INST(inx)
 {
     cpu->X++;
 }
 
+/*
+ * See DEY.
+ */
 DEFINE_INST(iny)
 {
     cpu->Y++;
 }
 
+/*
+ * This instruction will subtract the operand from the accumulator,
+ * again, "with carry". In this context, that means that if the carry
+ * bit is set, then we will subtract 1 again from the A register after
+ * the operand is subtracted. The result is stored in the accumulator.
+ */
 DEFINE_INST(sbc)
 {
     CARRY_BIT();