Update readme

README.md

@@ -5,26 +5,30 @@
 
 [API documentation](https://jarzka.github.io/namespacefy/docs/)
 
-namespacefy is a simple Clojure(Script) library which aims to make it easy to keep map keys namespaced, no matter where your data comes from.
+namespacefy is a small and simple Clojure(Script) library which aims to make it easy to keep map keys namespaced, no matter where your data comes from.
 
 # Introduction
 
-When data is fetched from a database or received from an external system, the output is often a map with unnamespaced keywords. This is often the desired end result. However, to avoid naming conflicts, it is often recommended to use namespaced keywords in Clojure. This library aims to solve this problem by providing simple helper functions to convert keys in maps to namespaced keywords, no matter where your data comes from. When the namespacing is not needed anymore (for example if you want to send the data to your JSON-loving neighbour), unnamespacing the map can be done easily before JSON conversion.
+When data is fetched from a database or received from an external system, the output is often a map or a collection of maps with unnamespaced keywords. This is often the desired end result. However, it is often recommended to use namespaced keywords in Clojure to avoid name conflicts and make the meaning of keywords more clear. This library aims to solve this problem by providing a simple helper function for keyword namespacing, no matter where your data comes from. When the namespacing is not needed anymore (for example if you want to send your data into an external system), unnamespacing the map can be done easily with another simple function call.
 
 # Installation
 
 Add the following line to your Leiningen project:
 
 ```clj
-[namespacefy "0.4"]
+[namespacefy "0.5.0"]
 ```
 
 # Usage
 
+## Require
+
 ```clj
 (:require [namespacefy.core :as namespacefy])
 ```
 
+## Namespacefy
+
 You can namespacefy keywords, maps or collection types with a single *namespacefy* function:
 
 ```clojure
@@ -34,10 +38,10 @@ You can namespacefy keywords, maps or collection types with a single *namespacef
            :points 7
            :foobar nil})
 
-(namespacefy data {:ns :product.domain.player
-                   :except #{:foobar}
-                   :custom {:points :product.domain.point/points}
-                   :inner {:tasks {:ns :product.domain.task}}})
+(namespacefy data {:ns :product.domain.player ; Base namespace for all keywords
+                   :except #{:foobar} ; Exceptions, do not namespacefy these keywords
+                   :custom {:points :product.domain.point/points} ; Namespacefy these keywords differently
+                   :inner {:tasks {:ns :product.domain.task}}}) ; How to handle keywords that contain collections or maps
 
 ;; We get the following output:
 ;; {:product.domain.player/name "Seppo"
@@ -48,6 +52,8 @@ You can namespacefy keywords, maps or collection types with a single *namespacef
 ;;  :foobar nil}"
 ```
 
+## Unnamespacefy
+
 To unnamespacefy the same data, use the *unnamespacefy* function. It also supports keywords, maps and collections:
 
 ```clojure
@@ -61,7 +67,11 @@ To unnamespacefy the same data, use the *unnamespacefy* function. It also suppor
 ;;  :foobar nil}
 ```
 
-There are also other helper functions available:
+Note that if unnamespacefying two keywords leads to the same result, you get an exception!
+
+## Helpers
+
+There are also some helper functions available for working effectively with the same keyword, regardless if it is namespaced or not. Generally speaking I do not recommend to mess with the same keyword in namespaced and unnamespaced form. However, these can be useful in situations in which you are changing your implementation from unnamespaced keywords to namespaced keywords.
 
 ```clojure
 ;; Get the specific key from a map, regardless if it is namespaced or not:

project.clj

@@ -1,4 +1,4 @@
-(defproject namespacefy "0.4"
+(defproject namespacefy "0.5.0"
   :description "Helper library for namespacing keywords"
   :dependencies [[org.clojure/clojure "1.8.0"]]
   :profiles {:dev {:dependencies [[org.clojure/test.check "0.9.0"]]}}