[doc] Update docs and examples

README.md

@@ -81,7 +81,7 @@ See [here][GitHub releases] for earlier releases.
 
 - Elegant, lightweight API that's **easy to use**, **easy to configure**, and **deeply flexible**.
 - **Sensible defaults** to make getting started **fast and easy**.
-- Extensive **beginner-oriented** [documentation][GitHub wiki], [docstrings](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso), and error messages.
+- Extensive **beginner-oriented** [documentation][GitHub wiki], [docstrings](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere), and error messages.
 
 ### Interop
 

examples.cljc

@@ -241,8 +241,8 @@
 ;; Handlers are just fns of 2 arities
 
 (defn my-basic-handler
-  ([signal] (println signal)) ; Arity-1 called when handling a signal
   ([])                        ; Arity-0 called when stopping the handler
+  ([signal] (println signal)) ; Arity-1 called when handling a signal
   )
 
 ;; If you're making a customizable handler for use by others, it's often
@@ -272,14 +272,14 @@
    (let [handler-fn ; Fn of exactly 2 arities
          (fn a-handler:my-fancy-handler ; Note fn naming convention
 
-           ([signal] ; Arity-1 called when handling a signal
-            ;; Do something useful with the given signal (write to
-            ;; console/file/queue/db, etc.). Return value is ignored.
-            )
-
            ([] ; Arity-0 called when stopping the handler
             ;; Flush buffers, close files, etc. May just noop.
             ;; Return value is ignored.
+            )
+
+           ([signal] ; Arity-1 called when handling a signal
+            ;; Do something useful with the given signal (write to
+            ;; console/file/queue/db, etc.). Return value is ignored.
             ))]
 
      ;; (Advanced, optional) You can use metadata to provide default

src/taoensso/telemere/impl.cljc

@@ -790,10 +790,11 @@
        Runs Telemere's registered interop checks and returns info useful
        for tests/debugging, e.g.:
 
-         {:tools-logging {:present? false}
-          :slf4j         {:present? true
-                          :sending->telemere?  true
-                          :telemere-receiving? true}
+         {:open-telemetry {:present? false}
+          :tools-logging  {:present? false}
+          :slf4j          {:present? true
+                           :sending->telemere?  true
+                           :telemere-receiving? true}
           ...}"
        []
        (enc/map-vals (fn [check-fn] (check-fn))

wiki/3-Config.md

@@ -25,7 +25,7 @@ See section [4-Handlers](./4-Handlers).
 
 ## tools.logging
 
-[`tools.logging`](https://github.com/clojure/tools.logging) can use Telemere as its logging implementation (backend).
+[`tools.logging`](https://github.com/clojure/tools.logging) can use Telemere as its logging implementation (backend). This'll let `tools.logging` calls create Telemere signals.
 
 To do this:
 
@@ -41,7 +41,7 @@ Verify successful interop with [`check-interop`](https://cljdoc.org/d/com.taoens
 
 ## Java logging
 
-[`SLF4Jv2`](https://www.slf4j.org/) can use Telemere as its logging backend.
+[`SLF4Jv2`](https://www.slf4j.org/) can use Telemere as its logging backend. This'll let SLF4J logging calls create Telemere signals.
 
 To do this, ensure that you have the following dependencies:
 
@@ -70,7 +70,7 @@ In this case logging will be forwarded:
 
 ## System streams
 
-The JVM's `System/out` and/or `System/err` streams can be set to flush to Telemere signals.
+The JVM's `System/out` and/or `System/err` streams can be set so that they'll create Telemere signals when flushed.
 
 To do this, call [`streams->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#streams-%3Etelemere!).
 

wiki/4-Handlers.md

@@ -176,8 +176,8 @@ Writing your own signal handlers for Telemere is straightforward, and a reasonab
 
 ```clojure
 (defn my-basic-handler
-  ([signal] (println signal)) ; Arity-1 called when handling a signal
   ([])                        ; Arity-0 called when stopping the handler
+  ([signal] (println signal)) ; Arity-1 called when handling a signal
   )
 ```
 
@@ -208,14 +208,14 @@ If you're making a customizable handler for use by others, it's often handy to d
    (let [handler-fn ; Fn of exactly 2 arities
          (fn a-handler:my-fancy-handler ; Note fn naming convention
 
-           ([signal] ; Arity-1 called when handling a signal
-            ;; Do something useful with the given signal (write to
-            ;; console/file/queue/db, etc.). Return value is ignored.
-            )
-
            ([] ; Arity-0 called when stopping the handler
             ;; Flush buffers, close files, etc. May just noop.
             ;; Return value is ignored.
+            )
+
+           ([signal] ; Arity-1 called when handling a signal
+            ;; Do something useful with the given signal (write to
+            ;; console/file/queue/db, etc.). Return value is ignored.
             ))]
 
      ;; (Advanced, optional) You can use metadata to provide default