Update comments for machine operations.

include/machine.h

@@ -97,11 +97,7 @@ class Machine {
     void copyFromRegister5(const InstructionWord& instruction, const Register5& reg, ComputerWord* word);
     /** Copy values considered the field value. */
     void copyToRegister2(const InstructionWord& instruction, const ComputerWord& word, Register2* reg);
-    /** Check whether the given value can be fitted into the given number of bytes.
-     * 
-     * Overflow will be triggered if it the value can not be fitted into 5 bytes.
-     * (Which means rI will not trigger overflow.)
-     */
+
     int32_t checkRange(int32_t value, int bytes = 5);
 
     /** Get one byte from the unit value of rA and rX. */

src/machine.cpp

@@ -547,6 +547,11 @@ void Machine::copyToRegister2(const InstructionWord& instruction, const Computer
     }
 }
 
+/** Check whether the given value can be fitted into the given number of bytes.
+ * 
+ * Overflow will be triggered if it the value can not be fitted into 5 bytes.
+ * (Which means rI will not trigger overflow.)
+ */
 int32_t Machine::checkRange(int32_t value, int bytes) {
     int32_t range = 1 << (6 * bytes);
     if (std::abs(value) >= range) {

src/machine_arithmetic.cpp

@@ -3,6 +3,10 @@
 
 namespace mixal {
 
+/** Add the values of rA and the word in the memory into rA.
+ * 
+ * @see overflow
+ */
 void Machine::executeADD(const InstructionWord& instruction) {
     int32_t valueA = rA.value();
     ComputerWord word;
@@ -13,6 +17,10 @@ void Machine::executeADD(const InstructionWord& instruction) {
     rA.set(checkRange(result));
 }
 
+/** Subtract the values of rA and the word in the memory into rA.
+ * 
+ * @see overflow
+ */
 void Machine::executeSUB(const InstructionWord& instruction) {
     int32_t valueA = rA.value();
     ComputerWord word;
@@ -24,6 +32,10 @@ void Machine::executeSUB(const InstructionWord& instruction) {
     rA.set(checkRange(result));
 }
 
+/** Multiply the values of rA and the word in the memory into rA and rX.
+ * 
+ * Note that overflow will never be triggered.
+ */
 void Machine::executeMUL(const InstructionWord& instruction) {
     int32_t valueA = rA.value();
     ComputerWord word;
@@ -35,6 +47,12 @@ void Machine::executeMUL(const InstructionWord& instruction) {
     rX.set(result % (1 << 30));
 }
 
+/** Divide the value of rA and rX with the value of the word in the memory.
+ * 
+ * The quotient will be placed in rA and the remainder will be placed in rX.
+ * 
+ * @see overflow
+ */
 void Machine::executeDIV(const InstructionWord& instruction) {
     int32_t valueA = std::abs(rA.value());
     int32_t valueX = std::abs(rX.value());

src/machine_comparison.cpp

@@ -3,6 +3,10 @@
 
 namespace mixal {
 
+/** Compare the values in rA or rX and the word in memory.
+ * 
+ * @see comparison
+ */
 void Machine::executeCMP(const InstructionWord& instruction, Register5* reg) {
     ComputerWord a, b;
     int32_t address = getIndexedAddress(instruction);
@@ -18,6 +22,10 @@ void Machine::executeCMP(const InstructionWord& instruction, Register5* reg) {
     }
 }
 
+/** Compare the values in rI and the word in memory.
+ * 
+ * @see comparison
+ */
 void Machine::executeCMPi(const InstructionWord& instruction) {
     int registerIndex = instruction.operation() - Instructions::CMP1 + 1;
     auto& rIi = rI(registerIndex);

src/machine_conversion.cpp

@@ -3,6 +3,10 @@
 
 namespace mixal {
 
+/** Convert chars in rA and rX to number, and save the result to rA.
+ * 
+ * @see overflow
+ */
 void Machine::executeNUM() {
     int64_t num = 0;
     for (int i = 1; i <= 5; ++i) {
@@ -20,6 +24,7 @@ void Machine::executeNUM() {
     rA.negative = negative;
 }
 
+/** Convert number in rA to chars, and save the result to rA and rX. */
 void Machine::executeCHAR() {
     int32_t num = std::abs(rA.value());
     for (int i = 5; i >= 1; --i) {

tests/cpp/test_machine_conversion.cpp

@@ -25,6 +25,15 @@ __TEST_U(TestMachineConversion, test_num) {
     __ASSERT_EQ(mixal::ComputerWord(false, 37, 57, 47, 30, 30), machine.rX);
 }
 
+__TEST_U(TestMachineConversion, test_num_overflow) {
+    machine.rA.set(false, 39, 39, 31, 32, 39);
+    machine.rX.set(false, 37, 57, 47, 30, 30);
+    auto result = mixal::Parser::parseLine("NUM", "", false);
+    machine.executeSingle(result.word);
+    __ASSERT_EQ(249301284, machine.rA.value());
+    __ASSERT_TRUE(machine.overflow);
+}
+
 __TEST_U(TestMachineConversion, test_char) {
     machine.rA.set(-12977699);
     machine.rX.set(false, 37, 57, 47, 30, 30);