diff --git a/main/src/taoensso/telemere/consoles.cljc b/main/src/taoensso/telemere/consoles.cljc index 2ddcdf6..7b389ec 100644 --- a/main/src/taoensso/telemere/consoles.cljc +++ b/main/src/taoensso/telemere/consoles.cljc @@ -13,7 +13,7 @@ #?(:clj (defn ^:public handler:console - "Experimental, subject to change. + "Alpha, subject to change. Returns a signal handler that: - Takes a Telemere signal (map). @@ -51,7 +51,7 @@ :cljs (defn ^:public handler:console - "Experimental, subject to change. + "Alpha, subject to change. If `js/console` exists, returns a signal handler that: - Takes a Telemere signal (map). @@ -88,7 +88,7 @@ #?(:cljs (defn ^:public handler:console-raw - "Experimental, subject to change. + "Alpha, subject to change. If `js/console` exists, returns a signal handler that: - Takes a Telemere signal (map). diff --git a/main/src/taoensso/telemere/impl.cljc b/main/src/taoensso/telemere/impl.cljc index 539a31c..3d49bc0 100644 --- a/main/src/taoensso/telemere/impl.cljc +++ b/main/src/taoensso/telemere/impl.cljc @@ -307,8 +307,7 @@ #?(:clj (defmacro ^:public with-signal - "Experimental, subject to change. - Executes given form, trapping errors. Returns the LAST signal created by form. + "Executes given form, trapping errors. Returns the LAST signal created by form. Useful for tests/debugging. Options: @@ -334,8 +333,7 @@ #?(:clj (defmacro ^:public with-signals - "Experimental, subject to change. - Like `with-signal` but returns {:keys [value error signals]}. + "Like `with-signal` but returns {:keys [value error signals]}. Useful for more advanced tests/debugging. Destructuring example: @@ -811,8 +809,7 @@ (defn add-interop-check! [source-id check-fn] (swap! interop-checks_ assoc source-id check-fn)) (defn ^:public check-interop - "Experimental, subject to change. - Runs Telemere's registered interop checks and returns info useful + "Runs Telemere's registered interop checks and returns info useful for tests/debugging, e.g.: {:open-telemetry {:present? false} diff --git a/main/src/taoensso/telemere/postal.clj b/main/src/taoensso/telemere/postal.clj index 91a5bfb..ccc2c2b 100644 --- a/main/src/taoensso/telemere/postal.clj +++ b/main/src/taoensso/telemere/postal.clj @@ -23,7 +23,7 @@ ]}) (defn handler:postal - "Experimental, subject to change. + "Alpha, subject to change. Needs `postal`, Ref. . diff --git a/main/src/taoensso/telemere/slack.clj b/main/src/taoensso/telemere/slack.clj index 3493c1c..6551085 100644 --- a/main/src/taoensso/telemere/slack.clj +++ b/main/src/taoensso/telemere/slack.clj @@ -23,7 +23,7 @@ ]}) (defn handler:slack - "Experimental, subject to change. + "Alpha, subject to change. Needs `clj-slack`, Ref. . diff --git a/main/src/taoensso/telemere/sockets.clj b/main/src/taoensso/telemere/sockets.clj index efe736c..416f938 100644 --- a/main/src/taoensso/telemere/sockets.clj +++ b/main/src/taoensso/telemere/sockets.clj @@ -49,7 +49,7 @@ (sw output))))))) (defn handler:udp-socket - "Highly experimental, subject to change. + "Highly experimental, subject to change! Feedback very welcome! Returns a signal handler that: diff --git a/main/src/taoensso/telemere/utils.cljc b/main/src/taoensso/telemere/utils.cljc index d2f14b7..e1447ba 100644 --- a/main/src/taoensso/telemere/utils.cljc +++ b/main/src/taoensso/telemere/utils.cljc @@ -21,7 +21,7 @@ ;;;; Unique IDs (UIDs) (defn nano-uid-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn nano-uid [root?]) that returns a random nano-style uid string like: \"r76-B8LoIPs5lBG1_Uhdy\" - 126 bit (21 char) root uid \"tMEYoZH0K-\" - 60 bit (10 char) non-root (child) uid" @@ -52,7 +52,7 @@ (comment ((nano-uid-fn) true)) (defn hex-uid-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn hex-uid [root?]) that returns a random hex-style uid string like: \"05039666eb9dc3206475f44ab9f3d843\" - 128 bit (32 char) root uid \"721fcef639a51513\" - 64 bit (16 char) non-root (child) uid" @@ -161,8 +161,7 @@ (comment (js-console-logger)) (defn error-signal? - "Experimental, subject to change. - Returns true iff given signal has an `:error` value, or a `:kind` or `:level` + "Returns true iff given signal has an `:error` value, or a `:kind` or `:level` that indicates that it's an error." #?(:cljs {:tag 'boolean}) [signal] @@ -238,7 +237,7 @@ #?(:clj (defn file-writer - "Experimental, subject to change. + "Alpha, subject to change. Opens the specified file and returns a stateful fn of 2 arities: [content] => Writes given content to file, or noops if closed. [] => Closes the writer. @@ -441,7 +440,7 @@ ;;;; Formatters (defn format-nsecs-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn format [nanosecs]) that: - Takes a long nanoseconds (e.g. runtime). - Returns a human-readable string like: @@ -468,7 +467,7 @@ (comment (println (format-clj-stacktrace (:trace (truss/ex-map (truss/ex-info "Ex2" {:k2 "v2"} (truss/ex-info "Ex1" {:k1 "v1"}))))))) (defn format-error-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn format [error]) that: - Takes a platform error (`Throwable` or `js/Error`). - Returns a human-readable error string." @@ -505,7 +504,7 @@ ;;;; (defn signal-preamble-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn preamble [signal]) that: - Takes a Telemere signal (map). - Returns a signal preamble ?string like: @@ -557,7 +556,7 @@ (comment (str (format-parent (str *ns*) {:id ::id1 :uid "uid1"}))) (defn signal-content-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn content [signal]) that: - Takes a Telemere signal (map). - Returns a human-readable signal content ?string (incl. data, ctx, etc.). @@ -636,7 +635,7 @@ ((signal-content-fn) (tel/with-signal (tel/event! ::ev-id {:data {:k1 "v1"}})))) (defn clean-signal-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn clean [signal]) that: - Takes a Telemere signal (map). - Returns a minimal signal (map) ready for printing, etc. @@ -701,7 +700,7 @@ (comment ((clean-signal-fn {:incl-keys #{:a}}) {:level :info, :id nil, :a "a", :b "b", :msg_ (delay "hi")})) (defn pr-signal-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn pr [signal]) that: - Takes a Telemere signal (map). - Returns a machine-readable signal string. @@ -766,7 +765,7 @@ (tel/with-signal (tel/event! ::ev-id {:kvs {:k1 "v1"}})))) (defn format-signal-fn - "Experimental, subject to change. + "Alpha, subject to change. Returns a (fn format [signal]) that: - Takes a Telemere signal (map). - Returns a human-readable signal string.