 ;; level-specific macros
 
 (defmacro trace
-  "Trace level logging using print-style args."
+  "Trace level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :trace ~@args))
 
 (defmacro debug
-  "Debug level logging using print-style args."
+  "Debug level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :debug ~@args))
 
 (defmacro info
-  "Info level logging using print-style args."
+  "Info level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :info ~@args))
 
 (defmacro warn
-  "Warn level logging using print-style args."
+  "Warn level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :warn ~@args))
 
 (defmacro error
-  "Error level logging using print-style args."
+  "Error level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :error ~@args))
 
 (defmacro fatal
-  "Fatal level logging using print-style args."
+  "Fatal level logging using print-style args.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([message & more] [throwable message & more])}
   [& args]
   `(logp :fatal ~@args))
 
 (defmacro tracef
-  "Trace level logging using format."
+  "Trace level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :trace ~@args))
 
 (defmacro debugf
-  "Debug level logging using format."
+  "Debug level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :debug ~@args))
 
 (defmacro infof
-  "Info level logging using format."
+  "Info level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :info ~@args))
 
 (defmacro warnf
-  "Warn level logging using format."
+  "Warn level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :warn ~@args))
 
 (defmacro errorf
-  "Error level logging using format."
+  "Error level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :error ~@args))
 
 (defmacro fatalf
-  "Fatal level logging using format."
+  "Fatal level logging using format.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([fmt & fmt-args] [throwable fmt & fmt-args])}
   [& args]
   `(logf :fatal ~@args))


(defmacro spyf
  "Evaluates expr and may write (format fmt result) to the log. Returns the
  result of expr. Defaults to :debug log level."
  ([fmt expr]
    `(spyf :debug ~fmt ~expr))
  ([level fmt expr]


(defmacro logf
  "Logs a message using a format string and args. Can optionally take a
  throwable as its second arg. See level-specific macros, e.g., debugf.
  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
  {:arglists '([level fmt & fmt-args] [level throwable fmt & fmt-args])}
  [level x & more]
  (if (or (instance? String x) (nil? more)) ; optimize for common case
