From f15db4313bf256dab171cf04dde8bd040349dbe5 Mon Sep 17 00:00:00 2001
From: mleku <me@mleku.dev>
Date: Sat, 23 Aug 2025 02:35:15 +0100
Subject: [PATCH] Add warning about improper JSON encoding with `json.Marshal`
 in `event.E` documentation and emphasize buffer pool usage.

---
 pkg/encoders/event/event.go | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/pkg/encoders/event/event.go b/pkg/encoders/event/event.go
index 04d1d0f..1b1e6a1 100644
--- a/pkg/encoders/event/event.go
+++ b/pkg/encoders/event/event.go
@@ -20,7 +20,13 @@ import (
 
 // E is the primary datatype of nostr. This is the form of the structure that
 // defines its JSON string-based format. Always use New() and Free() to create
-// and free event.E.
+// and free event.E to take advantage of the bufpool which greatly improves
+// memory allocation behaviour when encoding and decoding nostr events.
+//
+// WARNING: DO NOT use json.Marshal with this type because it will not properly
+// encode <, >, and & characters due to legacy bullcrap in the encoding/json
+// library. Either call MarshalJSON directly or use a json.Encoder with html
+// escaping disabled.
 type E struct {
 
 	// ID is the SHA256 hash of the canonical encoding of the event in binary format