From 94fec57c9e96390f3f12b04279aa47f8e4f347da Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Thu, 17 Apr 2025 17:16:48 +0200 Subject: [PATCH] [doc] Use consistent style for docstring opts --- main/src/taoensso/telemere/consoles.cljc | 4 +-- main/src/taoensso/telemere/files.clj | 8 +++--- main/src/taoensso/telemere/open_telemetry.clj | 6 ++--- main/src/taoensso/telemere/postal.clj | 2 +- main/src/taoensso/telemere/sockets.clj | 16 ++++++------ main/src/taoensso/telemere/utils.cljc | 26 +++++++++---------- 6 files changed, 31 insertions(+), 31 deletions(-) diff --git a/main/src/taoensso/telemere/consoles.cljc b/main/src/taoensso/telemere/consoles.cljc index 7b68163..7c0e669 100644 --- a/main/src/taoensso/telemere/consoles.cljc +++ b/main/src/taoensso/telemere/consoles.cljc @@ -23,7 +23,7 @@ Options: `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - `:stream` - `java.io.writer` + `:stream` ---- `java.io.writer` Defaults to `*err*` if `utils/error-signal?` is true, and `*out*` otherwise." ([] (handler:console nil)) @@ -95,7 +95,7 @@ Ref. . Options: - `:preamble-fn` - (fn [signal]) => string, see [1]. + `:preamble-fn` ----- (fn [signal]) => string, see [1]. `:format-nsecs-fn` - (fn [nanosecs]) => string. [1] `taoensso.telemere.utils/signal-preamble-fn`, etc." diff --git a/main/src/taoensso/telemere/files.clj b/main/src/taoensso/telemere/files.clj index e57c51d..4f8ab2f 100644 --- a/main/src/taoensso/telemere/files.clj +++ b/main/src/taoensso/telemere/files.clj @@ -286,18 +286,18 @@ Options: `:output-fn`- (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - `:path` - Path string of the target output file (default `logs/telemere.log`) + `:path` ----- Path string of the target output file (default `logs/telemere.log`) `:interval` - ∈ #{nil :daily :weekly :monthly} (default `:monthly`) When non-nil, causes interval-based archives to be maintained. - `:max-file-size` ∈ #{nil } (default 4MB) + `:max-file-size` - ∈ #{nil } (default 4MB) When `path` file size > ~this many bytes, rotates old content to numbered archives. - `:max-num-parts` ∈ #{nil } (default 8) + `:max-num-parts` - ∈ #{nil } (default 8) Maximum number of numbered archives to retain for any particular interval. - `:max-num-intervals` ∈ #{nil } (default 6) + `:max-num-intervals` - ∈ #{nil } (default 6) Maximum number of intervals (days/weeks/months) to retain." ([] (handler:file nil)) diff --git a/main/src/taoensso/telemere/open_telemetry.clj b/main/src/taoensso/telemere/open_telemetry.clj index e553d69..ae79d68 100644 --- a/main/src/taoensso/telemere/open_telemetry.clj +++ b/main/src/taoensso/telemere/open_telemetry.clj @@ -254,10 +254,10 @@ (see `telemere/otel-default-providers_` for default). Optional signal keys: - `:otel/attrs` - Attributes [1] to add to log records AND tracing spans/events - `:otel/log-attrs` - Attributes [1] to add to log records ONLY + `:otel/attrs` ------- Attributes [1] to add to log records AND tracing spans/events + `:otel/log-attrs` --- Attributes [1] to add to log records ONLY `:otel/trace-attrs` - Attributes [1] to add to tracing spans/events ONLY - `:otel/span-kind` - Span kind ∈ #{:internal (default) :client :server :consumer :producer} + `:otel/span-kind` --- Span kind ∈ #{:internal (default) :client :server :consumer :producer} [1] `io.opentelemetry.api.common.Attributes` or Clojure map with str/kw keys and vals ∈ #{nil boolean keyword string UUID long double string-vec long-vec double-vec boolean-vec}. diff --git a/main/src/taoensso/telemere/postal.clj b/main/src/taoensso/telemere/postal.clj index eed41ea..dd473ee 100644 --- a/main/src/taoensso/telemere/postal.clj +++ b/main/src/taoensso/telemere/postal.clj @@ -58,7 +58,7 @@ :cc \"engineering@example.com\" :X-MyHeader \"A custom header\"} - `:subject-fn` - (fn [signal]) => email subject string + `:subject-fn` ------ (fn [signal]) => email subject string `:subject-max-len` - Truncate subjects beyond this length (default 90) `:body-fn` - (fn [signal]) => email body content string, diff --git a/main/src/taoensso/telemere/sockets.clj b/main/src/taoensso/telemere/sockets.clj index 416f938..a3c2b1a 100644 --- a/main/src/taoensso/telemere/sockets.clj +++ b/main/src/taoensso/telemere/sockets.clj @@ -25,11 +25,11 @@ Can output signals as human or machine-readable (edn, JSON) strings. Options: - `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` + `:output-fn` --- (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` `:socket-opts` - {:keys [host port ssl? connect-timeout-msecs]} - `:host` - Destination TCP socket hostname string - `:port` - Destination TCP socket port int - `:ssl?` - Use SSL/TLS (default false) + `:host` ------ Destination TCP socket hostname string + `:port` ------ Destination TCP socket port int + `:ssl?` ------ Use SSL/TLS (default false) `:connect-timeout-msecs` - Connection timeout (default 3000 msecs) Limitations: @@ -59,10 +59,10 @@ Can output signals as human or machine-readable (edn, JSON) strings. Options: - `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - `:socket-opts` - {:keys [host port max-packet-bytes]} - `:host` - Destination UDP socket hostname string - `:port` - Destination UDP socket port int + `:output-fn` ---------- (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` + `:socket-opts` -------- {:keys [host port max-packet-bytes]} + `:host` ------------- Destination UDP socket hostname string + `:port` ------------- Destination UDP socket port int `:max-packet-bytes` - Max packet size (in bytes) before truncating output (default 512) `:truncation-warning-fn` diff --git a/main/src/taoensso/telemere/utils.cljc b/main/src/taoensso/telemere/utils.cljc index 3ef40f6..a8f6e87 100644 --- a/main/src/taoensso/telemere/utils.cljc +++ b/main/src/taoensso/telemere/utils.cljc @@ -352,10 +352,10 @@ Useful for basic handlers that write to a TCP socket, etc. Options: - `:ssl?` - Use SSL/TLS? + `:ssl?` ------------------ Use SSL/TLS? `:connect-timeout-msecs` - Connection timeout (default 3000 msecs) - `:socket-fn` - (fn [host port timeout]) => `java.net.Socket` - `:ssl-socket-fn` - (fn [socket host port]) => `java.net.Socket` + `:socket-fn` ------------- (fn [host port timeout]) => `java.net.Socket` + `:ssl-socket-fn` --------- (fn [socket host port]) => `java.net.Socket` Notes: - Writer should be manually closed after use (with zero-arity call). @@ -522,8 +522,8 @@ Options: `:format-inst-fn` - (fn format [instant]) => string. - `:format-id-fn` - (fn format [ns id]) => string. - `:format-msg-fn` - (fn format [msg]) => string." + `:format-id-fn` --- (fn format [ns id]) => string. + `:format-msg-fn` -- (fn format [msg]) => string." ([] (signal-preamble-fn nil)) ([{:keys [format-inst-fn format-id-fn format-msg-fn] :or {format-inst-fn (format-inst-fn) @@ -568,8 +568,8 @@ - Returns a human-readable signal content ?string (incl. data, ctx, etc.). Options: - `:raw-error?` - Retain unformatted error? (default false) - `:incl-keys` - Subset of signal keys to retain from those + `:raw-error?` ------ Retain unformatted error? (default false) + `:incl-keys` ------- Subset of signal keys to retain from those otherwise excluded by default: #{:kvs :host :thread} `:format-nsecs-fn` - (fn [nanosecs]) => string. `:format-error-fn` - (fn [error]) => string." @@ -654,8 +654,8 @@ Options: `:incl-nils?` - Include signal's keys with nil values? (default false) - `:incl-kvs?` - Include signal's app-level root kvs? (default false) - `:incl-keys` - Subset of signal keys to retain from those otherwise + `:incl-kvs?` -- Include signal's app-level root kvs? (default false) + `:incl-keys` -- Subset of signal keys to retain from those otherwise excluded by default: #{:schema :kvs :host :thread}" ([] (clean-signal-fn nil)) ([{:keys [incl-kvs? incl-nils? incl-keys] :as opts}] @@ -714,8 +714,8 @@ - Returns a machine-readable signal string. Options: - `:pr-fn` - ∈ #{ :edn (default) :json (Cljs only)} - `:clean-fn` - (fn [signal]) => clean signal map, see [1] + `:pr-fn` --------- ∈ #{ :edn (default) :json (Cljs only)} + `:clean-fn` ------ (fn [signal]) => clean signal map, see [1] `:incl-newline?` - Include terminating system newline? (default true) Examples: @@ -780,8 +780,8 @@ Options: `:incl-newline?` - Include terminating system newline? (default true) - `:preamble-fn` - (fn [signal]) => signal preamble string, see [1] - `:content-fn` - (fn [signal]) => signal content string, see [2] + `:preamble-fn` --- (fn [signal]) => signal preamble string, see [1] + `:content-fn` ---- (fn [signal]) => signal content string, see [2] [1] `taoensso.telemere.utils/signal-preamble-fn`, etc. [2] `taoensso.telemere.utils/signal-content-fn`, etc.