[logger] Allow report callback with two arguments returning a string

If the report callback is a fun of arity 2, then the second argument
is a map with the keys 'encoding', 'depth' and 'chars_limit', and the
fun must return a string which is size limited according to the given
depth and chars_limit.

If the report callback is a fun of arity 1, then it must return a
tuple containing a format string and a list of arguments. The
formatter will produce the string, and limit it's size.

1 files changed, 17 insertions, 1 deletions

diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index 23a289f2ee..dc68d5c761 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -194,10 +194,26 @@
 	the log event's <seealso marker="#metadata">metadata</seealso>.
 	The report callback is a convenience function that
 	the <seealso marker="#formatters">formatter</seealso> can use
-	to convert the report to a format string and arguments. The
+	to convert the report to a format string and arguments, or
+	directly to a string. The
 	formatter can also use its own conversion function, if no
 	callback is provided, or if a customized formatting is
 	desired.</p>
+      <p>The report callback must be a fun with one or two
+	arguments. If it takes one argument, this is the report
+	itself, and the fun returns a format string and arguments:</p>
+      <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>) -> {<seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso>,[term()]})</pre>
+      <p>If it takes two arguments, the first is the report, and the
+	second is a map containing extra data that allows direct
+	coversion to a string:</p>
+      <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>,<seealso marker="logger#type-report_cb_config"><c>logger:report_cb_config()</c></seealso>) -> <seealso marker="stdlib:unicode#type-chardata"><c>unicode:chardata()</c></seealso>)
+      </pre>
+      <p>The fun must obey the <c>encoding</c>, <c>depth</c>
+	and <c>chars_limit</c> parameters provided in the second
+	argument, as the formatter can not do anything useful of these
+	parameters with the returned string. This variant is used when
+	the formatting of the report depends on the size and encoding
+	parameters.</p>
       <p>Example, format string and arguments:</p>
       <code>logger:error("The file does not exist: ~ts",[Filename])</code>
       <p>Example, string:</p>