docs: add more comments

include/jvalidate/detail/string_adapter.h

@@ -12,6 +12,15 @@
 #include <jvalidate/status.h>
 
 namespace jvalidate::detail {
+/**
+ * @brief An ArrayAdapter implmenetation for JSON "types" which do not support
+ * arrays. This is for example caused when attempting to apply json schema
+ * validation to non-json types representation, such as a some forms of
+ * PropertyTree implementations.
+ *
+ * This is specifically provided for making StringAdapter compatible with the
+ * Adapter concept.
+ */
 template <typename CRTP> class UnsupportedArrayAdapter {
 public:
   size_t size() const { return 0; }
@@ -20,6 +29,14 @@ public:
   std::vector<CRTP>::const_iterator end() const { return {}; }
 };
 
+/**
+ * @brief An ObjectAdapter implmenetation for JSON "types" which do not support
+ * objects. This is for example caused when attempting to apply json schema
+ * validation to non-json types representation.
+ *
+ * This is specifically provided for making StringAdapter compatible with the
+ * Adapter concept.
+ */
 template <typename CRTP> class UnsupportedObjectAdapter {
 public:
   size_t size() const { return 0; }
@@ -29,6 +46,13 @@ public:
   std::map<std::string, CRTP>::const_iterator end() const { return {}; }
 };
 
+/**
+ * @brief An Adapter for strings, required for implmenting propertyNames
+ * constraints, which are applied to the keys of a JSON object.
+ *
+ * Unfortunately requires a large number of stub function implementations in
+ * order to satisfy adapter::Adapter AND Adapter concept.
+ */
 class StringAdapter final : public adapter::Adapter {
 public:
   using value_type = std::string_view;

include/jvalidate/regex.h

@@ -24,6 +24,11 @@ namespace jvalidate {
  *
  * If you need to use complicated patterns in your json schema, provide a
  * RegexEngine compatible wrapper for a different library, such as re2.
+ * std::regex does not support graphemes, meaning that multi-byte characters
+ * will need to wrapped in groups if you want to repeat them.
+ *
+ * Regular expressions are compiled using the default ECMAScript flags, which
+ * is almost, but not quite, compliant with the ECMA-262 standard.
  */
 class StdRegexEngine {
 private:
@@ -48,6 +53,26 @@ public:
 
 #if JVALIDATE_HAS_ICU
 namespace jvalidate {
+/**
+ * @brief An implementation of a regular expression "engine", for use with
+ * constraints like "pattern" and "patternProperties".
+ * Uses the "International Components for Unicode" (icu4c) library for its
+ * underlying implementation.
+ *
+ * These regular expressions operate on the level of graphemes, rather than
+ * characters. This means that multi-byte characters like emojis will be
+ * treated as singular characters for the purpose of "character sets" and
+ * repetition operators.
+ *
+ * This regex engine is not ECMA-262 compliant, which means that certain cases
+ * will not be recognized. This is a notice rather than a true issue, since
+ * many other languages' regex libraries (e.g. Python) are also not ECMA-262
+ * compliant.
+ *
+ * This means that we pass test cases that ECMAScript rejects, such as:
+ * - i18n digit characters are captured by \\d
+ * - i18n characters can be matched by \\w (if they are i18nword chars)
+ */
 class ICURegexEngine {
 private:
   std::unordered_map<std::string, std::unique_ptr<icu::RegexPattern>> cache_;