   (-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]

    [this a b c d e f g h i j k l m n o p q r s t rest]))

(defprotocol ICloneable
  "Protocol for cloning a value."
  (^clj -clone [value]
    "Creates a clone of value."))

(defprotocol ICounted
  "Protocol for adding the ability to count a collection in constant time."
  (^number -count [coll]
    "Calculates the count of coll in constant time. Used by cljs.core/count."))

(defprotocol IEmptyableCollection
  "Protocol for creating an empty collection."
  (-empty [coll]
    "Returns an empty collection of the same category as coll. Used
     by cljs.core/count."))

(defprotocol ICollection
  "Protocol for adding to a collection."
  (^clj -conj [coll o]
    "Returns a new collection of coll with o added to it. The new item
     should be added to the most efficient place, e.g.
     (conj [1 2 3 4] 5) => [1 2 3 4 5]
     (conj '(2 3 4 5) 1) => '(1 2 3 4 5)"))

#_(defprotocol IOrdinal
    (-index [coll]))

(defprotocol IIndexed
  "Protocol for collections to provide idexed-based access to their items."
  (-nth [coll n] [coll n not-found]
    "Returns the value at the index n in the collection coll.
     Returns not-found if index n is out of bounds and not-found is supplied."))

(defprotocol ASeq
  "Marker protocol indicating an array sequence.")

(defprotocol ISeq
  "Protocol for collections to provide access to their items as sequences."
  (-first [coll]
    "Returns the first item in the collection coll. Used by cljs.core/first.")
  (^clj -rest [coll]
    "Returns a new collection of coll without the first item. It should
     always return a seq, e.g.
     (rest []) => ()
     (rest nil) => ()"))

(defprotocol INext
  "Protocol for accessing the next items of a collection."
  (^clj-or-nil -next [coll]
    "Returns a new collection of coll without the first item. In contract to
     rest, it should return nil if there are no more items, e.g.
     (next []) => nil
     (next nil) => nil"))

(defprotocol ILookup
  "Protocol for looking up a value in a data structure."
  (-lookup [o k] [o k not-found]
    "Use k to look up a value in o. If not-found is supplied and k is not
     a valid value that can be used for look up, not-found is returned."))

(defprotocol IAssociative
  "Protocol for adding associativity to collections."
  (^boolean -contains-key? [coll k]
    "Returns true if k is a key in coll.")
  #_(-entry-at [coll k])
  (^clj -assoc [coll k v]
    "Returns a new collection of coll with a mapping from key k to
     value v added to it."))

(defprotocol IMap
  "Protocol for adding mapping functionality to collections."
  #_(-assoc-ex [coll k v])
  (^clj -dissoc [coll k]
    "Returns a new collection of coll without the mapping for key k."))

(defprotocol IMapEntry
  "Protocol for examining a map entry."
  (-key [coll]
    "Returns the key of the map entry.")
  (-val [coll]
    "Returns the value of the map entry."))

(defprotocol ISet
  "Protocol for adding set functionality to a collection."
  (^clj -disjoin [coll v]
    "Returns a new collection of coll that does not contain v."))

(defprotocol IStack
  "Protocol for collections to provide access to their items as stacks. The top
  of the stack should be accessed in the most efficient way for the different
  data structures."
  (-peek [coll]
    "Returns the item from the top of the stack. Is used by cljs.core/peek.")
  (^clj -pop [coll]
    "Returns a new stack without the item on top of the stack. Is used
     by cljs.core/pop."))

(defprotocol IVector
  "Protocol for adding vector functionality to collections."
  (^clj -assoc-n [coll n val]
    "Returns a new vector with value val added at position n."))

(defprotocol IDeref
  "Protocol for adding dereference functionality to a reference."
  (-deref [o]
    "Returns the value of the reference o."))

(defprotocol IDerefWithTimeout
  (-deref-with-timeout [o msec timeout-val]))

(defprotocol IMeta
  "Protocol for accessing the metadata of an object."
  (^clj-or-nil -meta [o]
    "Returns the metadata of object o."))

(defprotocol IWithMeta
  "Protocol for adding metadata to an object."
  (^clj -with-meta [o meta]
    "Returns a new object with value of o and metadata meta added to it."))

(defprotocol IReduce
  "Protocol for seq types that can reduce themselves.
  Called by cljs.core/reduce."
  (-reduce [coll f] [coll f start]
    "f should be a function of 2 arguments. If start is not supplied,
     returns the result of applying f to the first 2 items in coll, then
     applying f to that result and the 3rd item, etc."))

(defprotocol IKVReduce
  "Protocol for associative types that can reduce themselves
  via a function of key and val. Called by cljs.core/reduce-kv."
  (-kv-reduce [coll f init]
    "Reduces an associative collection and returns the result. f should be
     a function that takes three arguments."))

(defprotocol IEquiv
  "Protocol for adding value comparison functionality to a type."
  (^boolean -equiv [o other]
    "Returns true if o and other are equal, false otherwise."))

(defprotocol IHash
  "Protocol for adding hashing functionality to a type."
  (-hash [o]
    "Returns the hash code of o."))

(defprotocol ISeqable
  "Protocol for adding the ability to a type to be transformed into a sequence."
  (^clj-or-nil -seq [o]
    "Returns a seq of o, or nil if o is empty."))

(defprotocol ISequential
  "Marker interface indicating a persistent collection of sequential items")
