From 52bce66fd018bc213b2ba4c9b86739b7d9835677 Mon Sep 17 00:00:00 2001
From: Scott Bailey <Scott@TheBaileyFamily.org>
Date: Thu, 13 Apr 2023 09:06:33 -0500
Subject: [PATCH] Add docs

---
 tools/common.hpp | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tools/common.hpp b/tools/common.hpp
index b6ff14c..97333ec 100644
--- a/tools/common.hpp
+++ b/tools/common.hpp
@@ -7,8 +7,15 @@
 
 namespace antler {
 
+   /// Remove escape sequence character from input.
+   /// @note This is a SIMPLE algorithm that ONLY removes the first `\` in a 2 charachter sequence.
+   /// @todo Consider implementing more complicated transforms (e.g. convert "\t" to 0x09 or "\xFF" to 0xFF, etc).
+   /// @param input  Input string that may or may not contain escape characters.
+   /// @return The transformed string.
    std::string escape_transform(std::string input) {
       for(auto i=input.begin(); i != input.end(); ++i) {
+         // Only remove this char *if* there is a char following.
+         // Note: erase plus increment effectively steps over the char follwing the erased `\` (e.g. "\\-O2" becomes "\-O2").
          if(*i == '\\' && i+1 != input.end())
             i = input.erase(i);
       }