doc-strings and readme

README.md

@@ -1,6 +1,6 @@
 # cljs-uuid-utils
 
-ClojureScript micro-library with an implementation of a type 4, random UUID generator compatible with RFC-4122 and cljs.core/UUID, a uuid-string conformance validating predicate, and a UUID factory from uuid-string with conformance validation.
+ClojureScript micro-library with an implementation of a type 4, random UUID generator compatible with RFC-4122 and cljs.core/UUID (make-random-uuid), a uuid-string conformance validating predicate (valid-uuid?), and a UUID factory from uuid-string with conformance validation (make-uuid-from).
 
 ## Installation
 
@@ -12,17 +12,39 @@ Add the following to your `project.clj` dependencies:
 
 ## Usage
 
+Require cljs-uuid-utils library:
 
 ```clojure
 (ns myapp
-  (:use [cljs-uuid-utils :only [make-random-uuid valid-uuid? make-uuid-from]]))
-
-(def a-uuid (make-random-uuid))
-;; =>  #uuid "305e764d-b451-47ae-a90d-5db782ac1f2e"
-(type a-uuid)
-;; =>  cljs.core/UUID"
-(valid-uuid? a-uuid) 
-;; => "305e764d-b451-47ae-a90d-5db782ac1f2e" (truthy)
+  (:require [cljs-uuid-utils]))
+```
+
+REPL examples:
+
+```clojure
+
+ClojureScript:cljs.user> (def r (cljs-uuid-utils/make-random-uuid))
+#uuid "ec9b1b11-74b0-48a4-989c-7e939fd37dec"
+ClojureScript:cljs.user> (type r)
+cljs.core/UUID
+
+ClojureScript:cljs.user> (cljs-uuid-utils/valid-uuid? "NO-WAY")
+nil
+ClojureScript:cljs.user> (cljs-uuid-utils/valid-uuid? "ec9b1b11-74b0-48a4-989c-7e939fd37dec")
+"ec9b1b11-74b0-48a4-989c-7e939fd37dec"
+ClojureScript:cljs.user> (cljs-uuid-utils/valid-uuid? r)
+"ec9b1b11-74b0-48a4-989c-7e939fd37dec"
+
+ClojureScript:cljs.user> (cljs-uuid-utils/make-uuid-from "ec9b1b11-74b0-48a4-989c-7e939fd37dec")
+#uuid "ec9b1b11-74b0-48a4-989c-7e939fd37dec"
+ClojureScript:cljs.user> (cljs-uuid-utils/make-uuid-from "NO-WAY")
+nil
+ClojureScript:cljs.user> (cljs-uuid-utils/make-uuid-from r)
+#uuid "ec9b1b11-74b0-48a4-989c-7e939fd37dec"
+ClojureScript:cljs.user> (cljs-uuid-utils/make-uuid-from (UUID. "NO-WAY"))
+nil
+ClojureScript:cljs.user> (cljs-uuid-utils/make-uuid-from (UUID. "ec9b1b11-74b0-48a4-989c-7e939fd37dec"))
+#uuid "ec9b1b11-74b0-48a4-989c-7e939fd37dec"
 ```
 
 

project.clj

@@ -1,5 +1,5 @@
 (defproject org.clojars.franks42/cljs-uuid-utils "0.1.0"
-  :description "Micro library with ClojureScript implementation of a type 4, random UUID generator compatible with cljs.core/UUID"
+  :description "ClojureScript micro-library with an implementation of a type 4, random UUID generator compatible with RFC-4122 and cljs.core/UUID (make-random-uuid), a uuid-string conformance validating predicate (valid-uuid?), and a UUID factory from uuid-string with conformance validation (make-uuid-from)."
   :url "https://github.com/franks42/cljs-random-uuid"
   :license {:name "Eclipse Public License - v 1.0"
             :url "http://www.eclipse.org/legal/epl-v10.html"

src/cljs_uuid_utils.cljs

@@ -14,10 +14,13 @@
 
 
 (defn make-random-uuid
-  "Returns a new type 4 (pseudo randomly generated) cljs.core/UUID,
-  like: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
-  as per http://www.ietf.org/rfc/rfc4122.txt.
-  Usage:
+  "(make-random-uuid)  =>  new-uuid
+  Arguments and Values:
+  new-uuid --- new type 4 (pseudo randomly generated) cljs.core/UUID instance.
+  Description:
+  Returns pseudo randomly generated UUID,
+  like: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx as per http://www.ietf.org/rfc/rfc4122.txt.
+  Examples:
   (make-random-uuid)  =>  #uuid \"305e764d-b451-47ae-a90d-5db782ac1f2e\"
   (type (make-random-uuid)) => cljs.core/UUID"
   []
@@ -35,12 +38,16 @@
 
 
 (defn valid-uuid?
-  "Predicate to test whether the UUID string representation conforms to a
+  "(valid-uuid? maybe-uuid)  =>  truthy-falsy
+  Arguments and Values:
+  maybe-uuid --- string or UUID-instance that may represent a conformant UUID.
+  truthy-falsy --- Returns either the conforming UUID-string (truthy) or nil (falsy).
+  Description:
+  Predicate to test whether a string representation conforms to a
   \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" format where each x is a hexadecimal character.
   Input can be a maybe-uuid string or a cljs.core/UUID instance.
   Note that the current \"cljs.core/UUID.\" constructor does not check for any conformance.
-  Returns either the conforming UUID-string (truthy) or nil (falsy).
-  Usage:
+  Examples:
   (valid-uuid? \"NO-WAY\")  =>  nil
   (valid-uuid? \"4d7332e7-e4c6-4ca5-af91-86336c825e25\")  => \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"
   (valid-uuid? (UUID. \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"))  => \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"
@@ -54,10 +61,15 @@
 
 
 (defn make-uuid-from
-  "Returns a cljs.core/UUID instance or nil for a given string representation.
-  Input can be a string or a cljs.core/UUID instance,
-  and valid uuid-string conformance is enforced.
+  "(make-uuid-from maybe-uuid maybe-uuid)  =>  uuid-or-nil
+  Arguments and Values:
+  maybe-uuid --- string or UUID-instance that may represent a conformant UUID.
+  uuid-or-nil --- Returns either a cljs.core/UUID instance or nil.
+  Description:
+  Returns a cljs.core/UUID instance for a conformant UUID-string representation, or nil.
+  Input can be a string or a cljs.core/UUID instance.
   Note that if the input UUID-instance is not valid, nil is returned.
+  Examples:
   (make-uuid-from \"NO-WAY\")  =>  nil
   (make-uuid-from \"4d7332e7-e4c6-4ca5-af91-86336c825e25\")  => #uuid \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"
   (make-uuid-from (UUID. \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"))  => #uuid \"4d7332e7-e4c6-4ca5-af91-86336c825e25\"