Update documentation

src/json_tokens.hpp

@@ -1,12 +1,46 @@
 #pragma once
 #include <cstring>
 
+/**
+ * @brief Token structure for gperf-generated perfect hash table.
+ *
+ * Each JsonToken represents a known JSON key that can be efficiently
+ * looked up using perfect hash table generated by gperf. This eliminates
+ * the need for string comparisons during JSON parsing.
+ */
 struct JsonToken {
-  const char *name;
-  int token_id;
+  const char *name; ///< JSON key name (null-terminated string)
+  int token_id; ///< Unique identifier for this token (maps to JsonTokenType)
 };
 
+/**
+ * @brief Perfect hash table implementation for fast JSON key lookup.
+ *
+ * This class provides O(1) lookup of JSON keys using a perfect hash function
+ * generated by gperf at build time. The hash function guarantees no collisions
+ * for the known set of JSON keys used in WeaselDB commit requests.
+ *
+ * The implementation is generated from json_tokens.gperf and provides
+ * significantly faster JSON key recognition compared to string comparisons
+ * or standard hash tables.
+ *
+ * @example
+ * ```cpp
+ * const JsonToken* token = Perfect_Hash::lookup_json_token("request_id", 10);
+ * if (token) {
+ *   JsonTokenType type = static_cast<JsonTokenType>(token->token_id);
+ *   // Handle known token...
+ * }
+ * ```
+ */
 class Perfect_Hash {
 public:
+  /**
+   * @brief Look up a JSON token by name using perfect hash.
+   * @param str Pointer to the JSON key string (not required to be
+   * null-terminated)
+   * @param len Length of the JSON key string in bytes
+   * @return Pointer to JsonToken if found, nullptr if not a known token
+   */
   static const struct JsonToken *lookup_json_token(const char *str, size_t len);
 };