   (-pr-writer [o writer opts]))
 
 (defprotocol IPending
-  (^boolean -realized? [d]))
+  "Protocol for types which can have a deferred realization. Currently only
+  implemented by Delay."
+  (^boolean -realized? [d]
+    "Returns true if a value for d has been produced, false otherwise."))
 
 (defprotocol IWatchable
-  (-notify-watches [this oldval newval])
-  (-add-watch [this key f])
-  (-remove-watch [this key]))
+  "Protocol for types that can be watched. Currently only implemented by Atom."
+  (-notify-watches [this oldval newval]
+    "Calls all watchers with this, oldval and newval.")
+  (-add-watch [this key f]
+    "Adds a watcher function f to this. Keys must be unique per reference,
+     and can be used to remove the watch with -remove-watch.")
+  (-remove-watch [this key]
+    "Removes watcher that corresponds to key from this."))
 
 (defprotocol IEditableCollection
-  (^clj -as-transient [coll]))
+  "Protocol for collections which can transformed to transients."
+  (^clj -as-transient [coll]
+    "Returns a new, transient version of the collection, in constant time."))
 
 (defprotocol ITransientCollection
-  (^clj -conj! [tcoll val])
-  (^clj -persistent! [tcoll]))
+  "Protocol for adding basic functionality to transient collections."
+  (^clj -conj! [tcoll val]
+    "Adds value val to tcoll and returns tcoll.")
+  (^clj -persistent! [tcoll]
+    "Creates a persistent data structure from tcoll and returns it."))
 
 (defprotocol ITransientAssociative
-  (^clj -assoc! [tcoll key val]))
+  "Protocol for adding associativity to transient collections."
+  (^clj -assoc! [tcoll key val]
+    "Returns a new transient collection of tcoll with a mapping from key to
+     val added to it."))
 
 (defprotocol ITransientMap
-  (^clj -dissoc! [tcoll key]))
+  "Protocol for adding mapping functionality to transient collections."
+  (^clj -dissoc! [tcoll key]
+    "Returns a new transient collection of tcoll without the mapping for key."))
 
 (defprotocol ITransientVector
-  (^clj -assoc-n! [tcoll n val])
-  (^clj -pop! [tcoll]))
+  "Protocol for adding vector functionality to transient collections."
+  (^clj -assoc-n! [tcoll n val]
+    "Returns tcoll with value val added at position n.")
+  (^clj -pop! [tcoll]
+    "Returns tcoll with the last item removed from it."))
 
 (defprotocol ITransientSet
-  (^clj -disjoin! [tcoll v]))
+  "Protocol for adding set functionality to a transient collection."
+  (^clj -disjoin! [tcoll v]
+    "Returns tcoll without v."))
 
 (defprotocol IComparable
-  (^number -compare [x y]))
+  "Protocol for values that can be compared."
+  (^number -compare [x y]
+    "Returns a negative number, zero, or a positive number when x is logically
+     'less than', 'equal to', or 'greater than' y."))
 
 (defprotocol IChunk
-  (-drop-first [coll]))
+  "Protocol for accessing the items of a chunk."
+  (-drop-first [coll]
+    "Return a new chunk of coll with the first item removed."))
 
 (defprotocol IChunkedSeq
-  (-chunked-first [coll])
-  (-chunked-rest [coll]))
+  "Protocol for accessing a collection as sequential chunks."
+  (-chunked-first [coll]
+    "Returns the first chunk in coll.")
+  (-chunked-rest [coll]
+    "Return a new collection of coll with the first chunk removed."))
 
 (defprotocol IChunkedNext
-  (-chunked-next [coll]))
+  "Protocol for accessing the chunks of a collection."
+  (-chunked-next [coll]
+    "Returns a new collection of coll without the first chunk."))
 
 (defprotocol INamed
-  (^string -name [x])
-  (^string -namespace [x]))
-
-(defprotocol IAtom)
+  "Protocol for adding a name."
+  (^string -name [x]
+    "Returns the name String of x.")
+  (^string -namespace [x]
+    "Returns the namespace String of x."))
+
+(defprotocol IAtom
+  "Marker protocol indicating an atom.")
 
 (defprotocol IReset
-  (-reset! [o new-value]))
+  "Protocol for adding resetting functionality."
+  (-reset! [o new-value]
+    "Sets the value of o to new-value."))
 
 (defprotocol ISwap
-  (-swap! [o f] [o f a] [o f a b] [o f a b xs]))
+  "Protocol for adding swapping functionality."
+  (-swap! [o f] [o f a] [o f a b] [o f a b xs]
+    "Swaps the value of o to be (apply f current-value-of-atom args)."))
 
 (defprotocol IVolatile
-  (-vreset! [o new-value]))
+  "Protocol for adding volatile functionality."
+  (-vreset! [o new-value]
+    "Sets the value of volatile o to new-value without regard for the
+     current value. Returns new-value."))
 
 (defprotocol IIterable
-  (-iterator [coll]))
+  "Protocol for iterating over a collection."
+  (-iterator [coll]
+    "Returns an iterator for coll."))
 
 ;; Printing support
 

  "Marker protocol")

(defprotocol IFn
  (-invoke
    [this]
    [this a]

  "Marker interface indicating a record object")

(defprotocol IReversible
  "Protocol for reversing a seq."
  (^clj -rseq [coll]
    "Returns a seq of the items in coll in reversed order."))

(defprotocol ISorted
  "Protocol for a collection which can represent their items
  in a sorted manner. "
  (^clj -sorted-seq [coll ascending?]
    "Returns a sorted seq from coll in either ascending or descending order.")
  (^clj -sorted-seq-from [coll k ascending?]
    "Returns a sorted seq from coll in either ascending or descending order.
     If ascending is true, the result should contain all items which are > or >=
     than k. If ascending is false, the result should contain all items which
     are < or <= than k, e.g.
     (-sorted-seq-from (sorted-set 1 2 3 4 5) 3 true) => (3 4 5)
     (-sorted-seq-from (sorted-set 1 2 3 4 5) 3 false) => (3 2 1)")
  (-entry-key [coll entry]
    "Returns the key for entry.")
  (-comparator [coll]
    "Returns the comparator for coll."))

(defprotocol IWriter
  "Protocol for writing. Currently only implemented by StringBufferWriter."
  (-write [writer s]
    "Writes s with writer and returns the result.")
  (-flush [writer]
    "Flush writer."))

(defprotocol IPrintWithWriter
  "The old IPrintable protocol's implementation consisted of building a giant
