CLJS-1100: Add docstrings to core protocols.

Author: Maria Neise

src/cljs/cljs/core.cljs

@@ -305,6 +305,9 @@
   "Marker protocol")
 
 (defprotocol IFn
+  "Protocol for adding the ability to invoke an object as a function.
+  For example, a vector can also be used to look up a value:
+  ([1 2 3 4] 1) => 2"
   (-invoke
     [this]
     [this a]
@@ -330,84 +333,154 @@
     [this a b c d e f g h i j k l m n o p q r s t rest]))
 
 (defprotocol ICloneable
-  (^clj -clone [value]))
+  "Protocol for cloning a value."
+  (^clj -clone [value]
+    "Creates a clone of value."))
 
 (defprotocol ICounted
-  (^number -count [coll] "constant time count"))
+  "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
-  (-empty [coll]))
+  "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
-  (^clj -conj [coll o]))
+  "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
-  (-nth [coll n] [coll n not-found]))
+  "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)
+(defprotocol ASeq
+  "Marker protocol indicating an array sequence.")
 
 (defprotocol ISeq
-  (-first [coll])
-  (^clj -rest [coll]))
+  "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
-  (^clj-or-nil -next [coll]))
+  "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
-  (-lookup [o k] [o k not-found]))
+  "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
-  (^boolean -contains-key? [coll k])
+  "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]))
+  (^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]))
+  (^clj -dissoc [coll k]
+    "Returns a new collection of coll without the mapping for key k."))
 
 (defprotocol IMapEntry
-  (-key [coll])
-  (-val [coll]))
+  "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
-  (^clj -disjoin [coll v]))
+  "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
-  (-peek [coll])
-  (^clj -pop [coll]))
+  "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
-  (^clj -assoc-n [coll n val]))
+  "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
- (-deref [o]))
+  "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
-  (^clj-or-nil -meta [o]))
+  "Protocol for accessing the metadata of an object."
+  (^clj-or-nil -meta [o]
+    "Returns the metadata of object o."))
 
 (defprotocol IWithMeta
-  (^clj -with-meta [o meta]))
+  "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
-  (-reduce [coll f] [coll f start]))
+  "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
-  (-kv-reduce [coll f init]))
+  "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
-  (^boolean -equiv [o other]))
+  "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
-  (-hash [o]))
+  "Protocol for adding hashing functionality to a type."
+  (-hash [o]
+    "Returns the hash code of o."))
 
 (defprotocol ISeqable
-  (^clj-or-nil -seq [o]))
+  "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")
@@ -419,17 +492,33 @@
   "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
@@ -440,63 +529,109 @@
   (-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]))
+  "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)
+(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