From 0b9b5e62e886f9e7e7c17d558876f59f6a6e8c73 Mon Sep 17 00:00:00 2001
From: Clyne Sullivan <clyne@bitgloo.com>
Date: Sat, 21 Jan 2023 10:48:40 -0500
Subject: [PATCH] update documentation, fix some includes

---
 source/code.cpp          | 37 +++++++++++++++++++++++++------------
 source/gui_code.cpp      |  4 +---
 source/gui_help.cpp      | 11 +++++++++++
 source/main.cpp          |  8 +++-----
 source/stmdsp/stmdsp.cpp |  1 +
 5 files changed, 41 insertions(+), 20 deletions(-)

diff --git a/source/code.cpp b/source/code.cpp
index 8e3bd6c..f24bb5c 100644
--- a/source/code.cpp
+++ b/source/code.cpp
@@ -2,13 +2,14 @@
  * @file code.cpp
  * @brief Functionality for compiling and disassembling source code.
  *
- * Copyright (C) 2021 Clyne Sullivan
+ * Copyright (C) 2022 Clyne Sullivan
  *
  * Distributed under the GNU GPL v3 or later. You should have received a copy of
  * the GNU General Public License along with this program.
  * If not, see <https://www.gnu.org/licenses/>.
  */
 
+#include "main.hpp"
 #include "stmdsp.hpp"
 #include "stmdsp_code.hpp"
 
@@ -20,20 +21,32 @@
 #include <string>
 
 extern std::shared_ptr<stmdsp::device> m_device;
-void log(const std::string& str);
-
-std::ifstream compileOpenBinaryFile();
-void compileEditorCode(const std::string& code);
-void disassembleCode();
 
+// Stores the temporary file name currently used for compiling the algorithm.
 static std::string tempFileName;
+
+/**
+ * Generates a new temporary file name.
+ * @return A string containing the path and file name.
+ */
 static std::string newTempFileName();
-static bool codeExecuteCommand(
-    const std::string& command,
-    const std::string& file);
-static void stringReplaceAll(
-    std::string& str,
-    const std::string& what,
+
+/**
+ * Executes the given command using system(), collecting the text output in the
+ * given file.
+ * @param command The command to be executed.
+ * @param file The file to write command output to.
+ * @return True if the command was successful (i.e. returned zero).
+ */
+static bool codeExecuteCommand(const std::string& command, const std::string& file);
+
+/**
+ * Does an in-place replacement of all occurances of "what" with "with".
+ * @param str The text string to operate on.
+ * @param what The text to search for.
+ * @param with The text that will replace occurances of "what".
+ */
+static void stringReplaceAll(std::string& str, const std::string& what,
     const std::string& with);
 
 std::ifstream compileOpenBinaryFile()
diff --git a/source/gui_code.cpp b/source/gui_code.cpp
index 50fd0c8..b797e51 100644
--- a/source/gui_code.cpp
+++ b/source/gui_code.cpp
@@ -9,6 +9,7 @@
  * If not, see <https://www.gnu.org/licenses/>.
  */
 
+#include "code.hpp"
 #include "imgui.h"
 #include "backends/imgui_impl_sdl.h"
 #include "backends/imgui_impl_opengl2.h"
@@ -16,9 +17,6 @@
 
 #include <string>
 
-extern void compileEditorCode(const std::string& code);
-extern void disassembleCode();
-
 TextEditor editor; // file.cpp
 
 static std::string editorCompiled;
diff --git a/source/gui_help.cpp b/source/gui_help.cpp
index a17d9fa..b60387b 100644
--- a/source/gui_help.cpp
+++ b/source/gui_help.cpp
@@ -1,3 +1,14 @@
+/**
+ * @file gui_help.cpp
+ * @brief Defines the "Help" menu and provides its functionality.
+ *
+ * Copyright (C) 2022 Clyne Sullivan
+ *
+ * Distributed under the GNU GPL v3 or later. You should have received a copy of
+ * the GNU General Public License along with this program.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+
 #include "imgui.h"
 #include "ImGuiFileDialog.h"
 
diff --git a/source/main.cpp b/source/main.cpp
index aa9f7c4..a624499 100644
--- a/source/main.cpp
+++ b/source/main.cpp
@@ -2,7 +2,7 @@
  * @file main.cpp
  * @brief Program entry point and main loop.
  *
- * Copyright (C) 2021 Clyne Sullivan
+ * Copyright (C) 2022 Clyne Sullivan
  *
  * Distributed under the GNU GPL v3 or later. You should have received a copy of
  * the GNU General Public License along with this program.
@@ -13,7 +13,9 @@
 #include "backends/imgui_impl_sdl.h"
 #include "backends/imgui_impl_opengl2.h"
 
+#include "gui_help.hpp"
 #include "logview.h"
+#include "main.hpp"
 #include "stmdsp.hpp"
 
 #include <chrono>
@@ -37,10 +39,6 @@ bool guiInitialize();
 bool guiHandleEvents();
 void guiShutdown();
 void guiRender();
-void helpRenderMenu();
-void helpRenderDialog();
-
-void log(const std::string& str);
 
 static LogView logView;
 static ImFont *fontSans = nullptr;
diff --git a/source/stmdsp/stmdsp.cpp b/source/stmdsp/stmdsp.cpp
index 294e98f..c50845f 100644
--- a/source/stmdsp/stmdsp.cpp
+++ b/source/stmdsp/stmdsp.cpp
@@ -14,6 +14,7 @@
 #include <serial/serial.h>
 
 #include <algorithm>
+#include <array>
 
 extern void log(const std::string& str);