Merge branch 'docs' into develop

src/puget/ansi.clj

@@ -1,5 +1,7 @@
 (ns puget.ansi
-  (:require [clojure.string :as str]))
+  "This namespace defines functions to apply ANSI color codes to text."
+  (:require
+    [clojure.string :as str]))
 
 
 (def sgr-code

src/puget/data.clj

@@ -1,13 +1,13 @@
 (ns puget.data
-  "Code to handle structured data, usually represented as EDN."
+  "Code to handle custom data represented as tagged EDN values."
   (:require
     [clojure.data.codec.base64 :as b64])
   (:import
     (java.net URI)
     (java.util Date TimeZone UUID)))
 
 
-;; TAGGED VALUE PROTOCOL
+;; ## Tagged-value Protocol
 
 (defprotocol TaggedValue
   (edn-tag [this] "Return the EDN tag symbol for this data type.")
@@ -22,7 +22,7 @@
 
 
 
-;; EXTENSION FUNCTIONS
+;; ## Extension Functions
 
 (defmacro defprint-method
   "Defines a print-method for the given class which writes out the EDN
@@ -34,11 +34,9 @@
 
 
 (defmacro extend-tagged-value
-  "Extends the TaggedValue protocol with implementations which return the
-  given symbol as the tag and use the given expression to calculate the value.
-  The expression should resolve to a function which accepts one argument and
-  returns the serialized value. This macro also defines a print-method which
-  delegates to edn-str."
+  "Defines an EDN representation for a type `t`. The tag will be the symbol
+  given for `tag` and the value will be generated by applying `expr` to the
+  original value."
   [t tag expr]
   `(let [value-fn# ~expr]
      (extend-type ~t
@@ -50,20 +48,23 @@
 
 
 (defmacro extend-tagged-str
-  [c tag]
-  `(extend-tagged-value ~c ~tag str))
+  "Defines an EDN representation for the given type by converting it to a
+  string value."
+  [t tag]
+  `(extend-tagged-value ~t ~tag str))
 
 
 (defmacro extend-tagged-map
-  [c tag]
-  `(extend-tagged-value ~c ~tag
+  "Defines an EDN representation for the given type by converting it to a
+  map value."
+  [t tag]
+  `(extend-tagged-value ~t ~tag
      (comp (partial into {}) seq)))
 
 
 
-;; BUILT-IN EDN TAGS
+;; ## Basic EDN Types
 
-; #inst - Date-time instant as an ISO-8601 string.
 (defn- format-utc
   "Produces an ISO-8601 formatted date-time string from the given Date."
   [^Date date]
@@ -74,16 +75,18 @@
     (.format date)))
 
 
+;; `inst` tags a date-time instant represented as an ISO-8601 string.
 (extend-tagged-value Date 'inst format-utc)
 
 
-; #uuid - Universally-unique identifier string.
+;; `uuid` tags a universally-unique identifier string.
 (extend-tagged-str UUID 'uuid)
 
 
-; #bin - Binary data in the form of byte arrays.
+;; `bin` tags byte data represented as a base64-encoded string.
 (extend-tagged-value
-  (class (byte-array 0)) 'bin
+  (class (byte-array 0))
+  'bin
   #(->> % b64/encode (map char) (apply str)))
 
 
@@ -94,7 +97,7 @@
   (b64/decode (.getBytes bin)))
 
 
-; #uri - Universal Resource Identifier string.
+;; `uri` tags a Universal Resource Identifier string.
 (extend-tagged-str URI 'uri)
 
 
@@ -105,7 +108,7 @@
   (URI. uri))
 
 
-; #??? - default handling function
+;; Default tag reader.
 (defrecord GenericTaggedValue
   [tag value]
 

src/puget/order.clj

@@ -1,21 +1,23 @@
 (ns puget.order
-  "Total ordering comparator for Clojure values.")
+  "This namespace provides a total-ordering comparator for Clojure values.")
 
 
 (defn- type-priority
-  "Determines the 'priority' of the given value based on its type:
-  - nil
-  - Boolean
-  - Number
-  - Character
-  - String
-  - Keyword
-  - Symbol
-  - List
-  - Vector
-  - Set
-  - Map
-  - (all other types)"
+  "Determines a numeric priority for the given value based on its general type:
+
+  - `nil`
+  - `false`
+  - `true`
+  - numbers
+  - characters
+  - strings
+  - keywords
+  - symbols
+  - lists
+  - vectors
+  - sets
+  - maps
+  - all other types"
   [x]
   (let [predicates [nil? false? true? number? char? string?
                     keyword? symbol? list? vector? set? map?]