   "Marker interface indicating a record object")
 
 (defprotocol IReversible
-  (^clj -rseq [coll]))
+  "Protocol for reversing a seq."
+  (^clj -rseq [coll]
+    "Returns a seq of the items in coll in reversed order."))
 
 (defprotocol ISorted
-  (^clj -sorted-seq [coll ascending?])
-  (^clj -sorted-seq-from [coll k ascending?])
-  (-entry-key [coll entry])
-  (-comparator [coll]))
+  "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
-  (-write [writer s])
-  (-flush [writer]))
+  "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

  "Marker protocol")

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

  (-pr-writer [o writer opts]))

(defprotocol IPending
  "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
  "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
  "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
  "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
  "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
  "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
  "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
  "Protocol for adding set functionality to a transient collection."
  (^clj -disjoin! [tcoll v]
    "Returns tcoll without v."))

(defprotocol IComparable
  "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
  "Protocol for accessing the items of a chunk."
  (-drop-first [coll]
    "Return a new chunk of coll with the first item removed."))

(defprotocol IChunkedSeq
  "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
  "Protocol for accessing the chunks of a collection."
  (-chunked-next [coll]
    "Returns a new collection of coll without the first chunk."))

(defprotocol INamed
  "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
  "Protocol for adding resetting functionality."
  (-reset! [o new-value]
    "Sets the value of o to new-value."))

(defprotocol ISwap
  "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
  "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
  "Protocol for iterating over a collection."
  (-iterator [coll]
    "Returns an iterator for coll."))

;; Printing support

