Update fn docs to suggest using the readable ns

src/main/clojure/clojure/tools/logging.clj

@@ -81,7 +81,8 @@
 
 (defmacro logp
   "Logs a message using print style args. Can optionally take a throwable as its
-  second arg. See level-specific macros, e.g., debug."
+  second arg. See level-specific macros, e.g., debug.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   {:arglists '([level message & more] [level throwable message & more])}
   [level x & more]
   (if (or (instance? String x) (nil? more)) ; optimize for common case
@@ -95,7 +96,8 @@
 
 (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."
+  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
@@ -134,7 +136,8 @@
 
 (defmacro spyf
   "Evaluates expr and may write (format fmt result) to the log. Returns the
-  result of expr. Defaults to :debug log level."
+  result of expr. Defaults to :debug log level.
+  Use the 'logging.readable' namespace to avoid wrapping args in pr-str."
   ([fmt expr]
     `(spyf :debug ~fmt ~expr))
   ([level fmt expr]
@@ -211,73 +214,85 @@
 ;; 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))