From 2d8fa4d940a19a59551a59d79ca4dc38ce6ef104 Mon Sep 17 00:00:00 2001
From: munna0908 <88337208+munna0908@users.noreply.github.com>
Date: Tue, 17 Jun 2025 12:37:17 +0530
Subject: [PATCH] Apply suggestions from code review

Co-authored-by: Giuliano Mega <giuliano.mega@gmail.com>
---
 README.md            | 4 ++--
 serde/json/README.md | 8 +++++---
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 197afe6..8fb7f2e 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ import questionable/results
 type Person = object
   name {.serialize.}: string
   age {.serialize.}: int
-  address: string # Not serialized by default in OptIn mode
+  address: string # By default, serde will not serialize non-annotated fields (OptIn mode)
 
 # Create an instance
 let person = Person(name: "John Doe", age: 30, address: "123 Main St")
@@ -70,7 +70,7 @@ import std/streams
 
 # Define a type
 type Person = object
-  name: string
+  name: string # Unlike JSON, CBOR always serializes all fields, and they do not need to be annotated
   age: int
   address: string
 
diff --git a/serde/json/README.md b/serde/json/README.md
index cdc036c..ea2ae34 100644
--- a/serde/json/README.md
+++ b/serde/json/README.md
@@ -67,12 +67,14 @@ Types can be serialized and deserialized even without explicit annotations, usin
 
 ```nim
 # Type is not annotated
-# A default mode of OptIn (for serialize) and OptOut (for deserialize) is assumed.
+# If you don't annotate the type, serde assumes OptIn by default for serialization, and OptOut for 
+# deserialization. This means your types will be serialized to an empty string, which is probably not what you want:
 type MyObj1 = object
   field1: bool
   field2: bool
 
-# Type is annotated, but mode not specified
+# If you annotate your type but do not specify the mode, serde will default to OptOut for
+# both serialize and de-serialize, meaning all fields get serialized/de-serialized by default:
 # A default mode of OptOut is assumed for both serialize and deserialize.
 type MyObj2 {.serialize, deserialize.} = object
   field1: bool
@@ -390,7 +392,7 @@ assert errorResult.error of UnexpectedKindError
 
 ### Parsing JSON with `JsonNode.parse`
 
-For parsing raw JSON without immediate deserialization:
+To parse JSON string into a `JsonNode` tree instead of a deserializing to a concrete type, use `JsonNode.parse`:
 
 ```nim
 import pkg/serde/json