From 26934263b7ccda37f3f59b09d37990814e7fd24c Mon Sep 17 00:00:00 2001
From: Kevin Newton <kddnewton@gmail.com>
Date: Mon, 30 Oct 2023 23:33:04 -0400
Subject: [PATCH] Documentation for pm_strncasecmp

---
 include/prism.h                     |  1 +
 include/prism/defines.h             |  2 --
 include/prism/util/pm_strncasecmp.h | 27 +++++++++++++++++++++++++++
 prism.gemspec                       |  1 +
 src/util/pm_strncasecmp.c           | 13 ++++++++++---
 5 files changed, 39 insertions(+), 5 deletions(-)
 create mode 100644 include/prism/util/pm_strncasecmp.h

diff --git a/include/prism.h b/include/prism.h
index 9dcecbb9760..46bfae0fe03 100644
--- a/include/prism.h
+++ b/include/prism.h
@@ -5,6 +5,7 @@
 #include "prism/util/pm_buffer.h"
 #include "prism/util/pm_char.h"
 #include "prism/util/pm_memchr.h"
+#include "prism/util/pm_strncasecmp.h"
 #include "prism/util/pm_strpbrk.h"
 #include "prism/ast.h"
 #include "prism/diagnostic.h"
diff --git a/include/prism/defines.h b/include/prism/defines.h
index 531462a560d..f697b9e5547 100644
--- a/include/prism/defines.h
+++ b/include/prism/defines.h
@@ -49,6 +49,4 @@
 #   define snprintf _snprintf
 #endif
 
-int pm_strncasecmp(const uint8_t *string1, const uint8_t *string2, size_t length);
-
 #endif
diff --git a/include/prism/util/pm_strncasecmp.h b/include/prism/util/pm_strncasecmp.h
new file mode 100644
index 00000000000..6cf7aa80234
--- /dev/null
+++ b/include/prism/util/pm_strncasecmp.h
@@ -0,0 +1,27 @@
+#ifndef PRISM_STRNCASECMP_H
+#define PRISM_STRNCASECMP_H
+
+#include "prism/defines.h"
+
+#include <ctype.h>
+#include <stddef.h>
+#include <stdint.h>
+
+/**
+ * Compare two strings, ignoring case, up to the given length. Returns 0 if the
+ * strings are equal, a negative number if string1 is less than string2, or a
+ * positive number if string1 is greater than string2.
+ *
+ * Note that this is effectively our own implementation of strncasecmp, but it's
+ * not available on all of the platforms we want to support so we're rolling it
+ * here.
+ * 
+ * @param string1 The first string to compare.
+ * @param string2 The second string to compare
+ * @param length The maximum number of characters to compare.
+ * @return 0 if the strings are equal, a negative number if string1 is less than
+ *     string2, or a positive number if string1 is greater than string2.
+ */
+int pm_strncasecmp(const uint8_t *string1, const uint8_t *string2, size_t length);
+
+#endif
diff --git a/prism.gemspec b/prism.gemspec
index f93035aa187..5662fd4284a 100644
--- a/prism.gemspec
+++ b/prism.gemspec
@@ -57,6 +57,7 @@ Gem::Specification.new do |spec|
     "include/prism/util/pm_memchr.h",
     "include/prism/util/pm_newline_list.h",
     "include/prism/util/pm_state_stack.h",
+    "include/prism/util/pm_strncasecmp.h",
     "include/prism/util/pm_string.h",
     "include/prism/util/pm_string_list.h",
     "include/prism/util/pm_strpbrk.h",
diff --git a/src/util/pm_strncasecmp.c b/src/util/pm_strncasecmp.c
index fce11835e05..2240bf81107 100644
--- a/src/util/pm_strncasecmp.c
+++ b/src/util/pm_strncasecmp.c
@@ -1,7 +1,14 @@
-#include <ctype.h>
-#include <stddef.h>
-#include <stdint.h>
+#include "prism/util/pm_strncasecmp.h"
 
+/**
+ * Compare two strings, ignoring case, up to the given length. Returns 0 if the
+ * strings are equal, a negative number if string1 is less than string2, or a
+ * positive number if string1 is greater than string2.
+ *
+ * Note that this is effectively our own implementation of strncasecmp, but it's
+ * not available on all of the platforms we want to support so we're rolling it
+ * here.
+ */
 int
 pm_strncasecmp(const uint8_t *string1, const uint8_t *string2, size_t length) {
     size_t offset = 0;