From 387e3f34e1fe8d9cd309abb4971de8d180aa3d4f Mon Sep 17 00:00:00 2001
From: Leon P Smith <leon@melding-monads.com>
Date: Fri, 3 Jun 2011 02:00:38 -0400
Subject: [PATCH] Initial haddock comments and .cabal description

---
 json-builder.cabal       | 39 ++++++++++++++++++++++++++-------------
 src/Data/Json/Builder.hs | 28 +++++++++++++++++++++++++++-
 2 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/json-builder.cabal b/json-builder.cabal
index 59cdfb1..403aea1 100644
--- a/json-builder.cabal
+++ b/json-builder.cabal
@@ -5,28 +5,41 @@ License:             BSD3
 License-file:        LICENSE
 Author:              Leon P Smith
 Maintainer:          leon@melding-monads.com
+Stability:           experimental
 Copyright:           (c) 2011 Leon P Smith
-Category:            Text, Web, JSON
+Category:            JSON
 Build-type:          Simple
-Cabal-version:       >=1.2
-
+Cabal-version:       >= 1.6
+homepage:            http://github.com/lpsmith/json-builder
+bug-reports:         http://github.com/lpsmith/json-builder/issues
+description:
+    Most json packages define a data structure that corresponds to json values.
+    To serialize other values to a json string, then that value must be
+    marshalled into the json data structure.
+    .
+    This library avoids this marshalling step, and is thus potentially more
+    efficient when serializing arbitrary data structures.  Unfortunately
+    json-builder cannot yet read or process json data,  and it's not clear
+    to me yet how pull a similar kind of trick to avoid unnecessary data
+    structures when parsing json data into arbitrary data types.
 
 Library
   hs-source-dirs: src
-  -- Modules exported by the library.
   Exposed-modules:     Data.Json.Builder
-  
-  -- Packages needed in order to build this package.
+
   Build-depends:       base >= 4 && < 5,
                        blaze-builder,
+                       blaze-textual,
                        bytestring,
                        containers,
                        text,
-                       blaze-textual,
                        utf8-string
-  
-  -- Modules not exported by this package.
-  -- Other-modules:       
-  
-  -- Extra tools (e.g. alex, hsc2hs, ...) needed to build the source.
-  -- Build-tools:         
+
+source-repository head
+  type:     git
+  location: http://github.com/lpsmith/json-builder
+
+source-repository this
+  type:     git
+  location: http://github.com/lpsmith/json-builder
+  tag:      v0.0
diff --git a/src/Data/Json/Builder.hs b/src/Data/Json/Builder.hs
index 9e6cb3a..1507733 100644
--- a/src/Data/Json/Builder.hs
+++ b/src/Data/Json/Builder.hs
@@ -58,14 +58,27 @@ import           Data.ByteString.Internal ( c2w )
 import qualified Data.Text              as T
 import qualified Data.Text.Lazy         as TL
 
----- The "core" of json-builder
+-- | The 'Key' typeclass represents types that are rendered 
+-- into json strings.  They are special because only strings 
+-- can appear as field names of a json objects.
 
 class Value a => Key a where
   escape           :: a -> Escaped
 
+-- | The 'Value' typeclass represents types that can be rendered
+-- into valid json syntax.
+
 class Value a where
   toBuilder        :: a -> Blaze.Builder
 
+-- | The 'Escaped' type is a special Builder value that represents a UTF-8 
+-- encoded string with all necessary characters json-escaped.  These builders
+-- must not render the opening or closing quotes,  which are instead rendered
+-- by 'toBuilder'.  This is so that Json strings can be efficiently constructed
+-- from multiple Haskell strings without actually concatinating the Haskell 
+-- strings (which might require some kind of conversion in addition to
+-- concatination.)
+
 newtype Escaped = Escaped Blaze.Builder deriving (Monoid)
 
 instance Key Escaped where
@@ -81,6 +94,12 @@ comma b f True  =                        b `mappend` f False
 comma b f False = fromChar ',' `mappend` b `mappend` f False
 {-# INLINE comma #-}
 
+-- |  The 'Object' type represents a builder that constructs syntax for a
+-- json object.  It has a singleton constructor 'row', and an instance of
+-- monoid, so that arbitrary objects can be constructed.  Note that 
+-- duplicate field names will appear in the output, so it is up to the
+-- user of this interface to avoid duplicate field names. 
+
 newtype Object = Object CommaTracker
 
 instance Value Object where
@@ -90,11 +109,16 @@ instance Monoid Object where
   mempty = Object id
   mappend (Object f) (Object g) = Object (f . g)
 
+-- | The 'row' constructs a json object consisting of exactly one field.
+-- These objects can be concatinated using 'mappend'. 
 row :: (Key k, Value a) => k -> a -> Object
 row k a = Object syntax
   where
     syntax = comma (mconcat [ toBuilder k, fromChar ':',  toBuilder a ])
 
+-- |  The 'Array' type represents a builder that constructs syntax for a
+-- json array.  It has a singleton constructor 'element' and an instance of
+-- monoid, so that arbitrary arrays can be constructed.
 
 newtype Array = Array CommaTracker
 
@@ -105,6 +129,8 @@ instance Monoid Array where
   mempty = Array id
   mappend (Array f) (Array g) = Array (f . g)
 
+-- |  The 'element' function constructs a json array consisting of exactly
+-- one value.  These arrays can be concatinated using 'mappend'.
 element :: Value a => a -> Array
 element a = Array $ comma (toBuilder a)