From 06e01dd6987c8fd752db0c78693db747b68f6b21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Valim?= <jose.valim@dashbit.co>
Date: Wed, 27 Nov 2024 18:48:00 +0100
Subject: [PATCH] Docs

---
 lib/elixir/lib/json.ex | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/lib/elixir/lib/json.ex b/lib/elixir/lib/json.ex
index 00da13498d0..671a6762594 100644
--- a/lib/elixir/lib/json.ex
+++ b/lib/elixir/lib/json.ex
@@ -1,6 +1,25 @@
 defprotocol JSON.Encoder do
   @moduledoc """
   A protocol for custom JSON encoding of data structures.
+
+  If you have a struct, you can derive the implementation of this protocol
+  by specifying which fields should be encoded to JSON:
+
+        @derive {JSON.Encoder, only: [....]}
+        defstruct ...
+
+  It is also possible to encode all fields or skip some fields via the
+  `:except` option, although this should be used carefully to avoid
+  accidentally leaking private information when new fields are added:
+
+      @derive JSON.Encoder
+      defstruct ...
+
+  Finally, if you don't own the struct you want to encode to JSON,
+  you may use Protocol.derive/3 placed outside of any module:
+
+      Protocol.derive(JSON.Encoder, NameOfTheStruct, only: [...])
+      Protocol.derive(JSON.Encoder, NameOfTheStruct)
   """
 
   @undefined_impl_description """