From 92013c4b46948ab92cdbf2f85ff33ebf1d6a58f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ionu=C8=9B=20Ar=C8=9B=C4=83ri=C8=99i?=
 <mapleoin@lavabit.com>
Date: Wed, 10 Apr 2013 23:06:40 +0200
Subject: [PATCH] document corner-cases with map_by schemas

---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index 9abf799..cff07eb 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,23 @@ Then you can access the extension fields in Clojure:
 => {:max 100.0 :min -100.0}
 ```
 
+Note that you do not have to specify the _key_ in a map which uses `map_by`; clojure-protobuf will just fill it out for you:
+
+```clojure
+(protobuf Photo :id 7 :path "/example/path" :tags {4 {:x_coord 100}})
+=> {:id 7, :path "/example/path", :tags {4 {:person-id 4, :x-coord 100}}}
+```
+
+Specifying different values will cause clojure-protobuf to override the outer one:
+
+```clojure
+(protobuf Photo :id 7 :path "/example/path" :tags {4 {:person_id 50 :x_coord 100}})
+=> {:id 7, :path "/example/path", :tags {50 {:person-id 50, :x-coord 100}}}
+```
+
+Because of this behaviour, valid input to `(protobuf-dump (protobuf P ...))` can be different from the output of `(protobuf-load P ...)`.
+
+
 ## Getting Help
 
 If you have any questions or need help, you can find us on IRC in [#flatland](irc://irc.freenode.net/#flatland).