Experimental warnings

Author: daveray

language-adaptors/rxjava-clojure/src/main/clojure/rx/lang/clojure/blocking.clj

@@ -14,6 +14,8 @@
 (set! *warn-on-reflection* true)
 
 (defmacro ^:private with-ex-unwrap
+  "The blocking ops wrap errors stuff in RuntimeException because of stupid Java.
+  This tries to unwrap them so callers get the exceptions they expect."
   [& body]
   `(try
     ~@body
@@ -80,7 +82,7 @@
 (defn single
   "*Blocks* and waits for the first value emitted by the given observable.
 
-   An error is thrown if more then one value is produced.
+   An error is thrown if zero or more then one value is produced.
   "
   [observable]
   (with-ex-unwrap

language-adaptors/rxjava-clojure/src/main/clojure/rx/lang/clojure/chunk.clj

@@ -6,7 +6,11 @@
 (set! *warn-on-reflection* true)
 
 (defn chunk
-  "Same as rx.Observable.merge(Observable<Observable<T>>) but the input Observables
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  TODO RxJava's much bigger since this was written. Is there something built in?
+
+  Same as rx.Observable.merge(Observable<Observable<T>>) but the input Observables
   are \"chunked\" so that at most chunk-size of them are \"in flight\" at any given
   time.
 
@@ -19,7 +23,7 @@
   Example:
 
     (->> users
-         (map #(-> (GetUserCommand. %) .toObservable))
+         (rx/map #(-> (GetUserCommand. %) .toObservable))
          (chunk 10))
 
   See:

language-adaptors/rxjava-clojure/src/main/clojure/rx/lang/clojure/graph.clj

@@ -18,7 +18,9 @@
     (.cache o)))
 
 (defn let-o*
-  "Given a graph description, returns an observable that emits a single
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  Given a graph description, returns an observable that emits a single
   map of observables all hooked up and ready for subscription.
 
   A graph is a map from name to a map with keys:
@@ -73,7 +75,9 @@
         (assoc ::non-terminals non-terminals))))
 
 (defmacro let-o
-  "Similar to clojure.core/let, but bindings are Observables and the result of the body
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  Similar to clojure.core/let, but bindings are Observables and the result of the body
   must be an Observable. Binding names must start with ?. Binding order doesn't matter
   and any binding is visible to all other expressions as long as no cycles are produced
   in the resulting Observable expression.

language-adaptors/rxjava-clojure/src/main/clojure/rx/lang/clojure/realized.clj

@@ -34,7 +34,9 @@
     :else                       (->post-proc (rx.Observable/just v))))
 
 (defn realized-map
-  "See let-realized.
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  See let-realized.
 
   Given a map from key to observable, returns an observable that emits a single
   map from the same keys to the values emitted by their corresponding observable.
@@ -92,12 +94,16 @@
         (.reduce {} (iop/fn* merge))))) ; do the map merge dance
 
 (defn ^rx.Observable realized-map*
-  "Same as realized-map, but takes a map argument rather than key-value pairs."
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  Same as realized-map, but takes a map argument rather than key-value pairs."
   [map-description]
   (apply realized-map (apply concat map-description)))
 
 (defmacro let-realized
-  "'let' version of realized map.
+  "EXTREMELY EXPERIMENTAL AND SUBJECT TO CHANGE OR DELETION
+
+  'let' version of realized map.
 
     (let-realized [a (make-observable)]
       (* 2 a))