feat: add command documentation comments and implement sum command

Author: nholthaus

examples/nestedFor.script

@@ -7,9 +7,8 @@ var count 99
 
 for i 0 10 inc
     for j 10 0 dec
-        echo .
-#        sum neg_j_minus_one -1 $j
-#        sum low 10 $neg_j_minus_one
+        sum neg_j_minus_one -1 $j
+        sum low 10 $neg_j_minus_one
 #        mul high $i 10
 #        sum value $high $low
 #        if_lte $value $count

src/commands/command

@@ -87,4 +87,4 @@
 #define REMOVE_METADATA(name) ScriptInstance::removeMetadata(name)
 
 // Writes a standard command error message with the command name and line number.
-#define ERROR(msg) std::cerr << std::endl << "ERROR: '" << COMMAND << "' " << msg << " : " << SOURCE; std::exit(1);
+#define ERROR(msg) {std::cerr << std::endl << "ERROR: '" << COMMAND << "' " << msg << " : " << SOURCE; std::exit(1);}

src/commands/comments.cpp

@@ -1,6 +1,19 @@
 #include <command>
 #include <no_op.h>
 
+/*
+NAME
+    comments - register comment tokens as no-op commands
+
+SYNOPSIS
+    # <text>
+    // <text>
+    /// <text>
+
+DESCRIPTION
+    Treats comment-prefixed lines as valid commands that do nothing when
+    executed.
+*/
 
 namespace
 {

src/commands/echo.cpp

@@ -1,5 +1,16 @@
 #include <command>
 
+/*
+NAME
+    echo - write text to standard output
+
+SYNOPSIS
+    echo <text>
+
+DESCRIPTION
+    Expands variables in the provided text and writes the result without
+    appending a trailing newline.
+*/
 REGISTER_COMMAND
 {
 	auto output = args;

src/commands/end_for.cpp

@@ -1,5 +1,16 @@
 #include <command>
 
+/*
+NAME
+    end_for - jump back to the matching for loop
+
+SYNOPSIS
+    end_for
+
+DESCRIPTION
+    Uses loop metadata recorded by for to continue iteration or fall through
+    when the loop is complete.
+*/
 REGISTER_COMMAND
 {
 	try

src/commands/endl.cpp

@@ -1,7 +1,17 @@
 #include <command>
 
+/*
+NAME
+    endl - write a newline to standard output
+
+SYNOPSIS
+    endl
+
+DESCRIPTION
+    Flushes a single line ending to standard output.
+*/
 REGISTER_COMMAND
 {
 	std::cout << std::endl;
 	std::cout.flush();
-};
+};

src/commands/for.cpp

@@ -1,6 +1,18 @@
 #include <command>
 #include <findMatch.h>
 
+/*
+NAME
+    for - execute a counted loop
+
+SYNOPSIS
+    for <loop_var> <start> <end> <unary_func>
+
+DESCRIPTION
+    Iterates from <start> toward the exclusive <end> bound using unary_func,
+    which must currently be inc or dec. The current value is stored in
+    <loop_var> for the body of the loop.
+*/
 REGISTER_COMMAND
 {
 	auto splitArgs = utils::split(args);

src/commands/ret.cpp

@@ -2,6 +2,17 @@
 #include <format>
 #include <split.h>
 
+/*
+NAME
+    ret - return from the current script frame
+
+SYNOPSIS
+    ret <value>
+
+DESCRIPTION
+    Returns control to the previous stack frame with the given integer status.
+    If there is no previous frame, the process exits with that status code.
+*/
 REGISTER_COMMAND
 {
 	try

src/commands/scope.cpp

@@ -1,6 +1,17 @@
 #include <command>
 #include <no_op.h>
 
+/*
+NAME
+    scope - register brace tokens as no-op commands
+
+SYNOPSIS
+    {
+    }
+
+DESCRIPTION
+    Treats brace-only lines as valid commands that do nothing when executed.
+*/
 
 namespace
 {

src/commands/sum.cpp

@@ -0,0 +1,33 @@
+#include <command>
+
+/*
+NAME
+    sum - add two integers and store the result
+
+SYNOPSIS
+    sum <output> <a> <b>
+
+DESCRIPTION
+    Expands variables in the numeric inputs, adds the two integer values, and
+    stores the result in <output>.
+*/
+REGISTER_COMMAND
+{
+	auto vars = args;
+	DEREFERENCE(vars);
+	const auto& splitVars = utils::split(vars);
+
+	if (splitVars.size() != 3)
+		ERROR("requires 3 arguments <output> <a> <b>");
+
+	try
+	{
+		const int a = std::stoi(splitVars[1].c_str());
+		const int b = std::stoi(splitVars[2].c_str());
+		SET_VARIABLE(splitVars[0], std::to_string(a + b));
+	}
+	catch (std::exception& e)
+	{
+		ERROR("Input values must be integers");
+	}
+};