File 3512-kernel-Expand-documentation-of-logger-log-with-fun.patch of Package erlang

From 4fe05a5dabd057ada2d637f38173e938e4e8468e Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Thu, 11 Feb 2021 09:52:33 +0100
Subject: [PATCH 2/2] kernel: Expand documentation of logger:log with fun

---
 lib/kernel/doc/src/logger.xml         | 36 +++++++++++++++++++++++++--
 lib/kernel/doc/src/logger_chapter.xml | 18 +++++++++-----
 2 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 2f2417690b..acf695d112 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -450,12 +450,44 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
       <type variable="FunArgs" name_i="4"/>
       <type variable="Metadata"/>
       <desc>
-        <p>Log the given message.</p>
+        <p>Create a log event at the given
+          <seeguide marker="logger_chapter#log_level">log level</seeguide>,
+          with the given <seeguide marker="logger_chapter#log_message">message</seeguide>
+          to be logged and
+          <seeguide marker="logger_chapter#metadata"><em>metadata</em></seeguide>.
+        Examples:</p>
+        <code>
+%% A plain string
+logger:log(info, "Hello World").
+%% A plain string with metadata
+logger:log(debug, "Hello World", #{ meta => data }).
+%% A format string with arguments
+logger:log(warning, "The roof is on ~ts",[Cause]).
+%% A report
+logger:log(warning, #{ what => roof, cause => Cause }).
+        </code>
+        <p>The message and metadata can either be given directly in the arguments,
+          or returned from a fun. Passing a fun instead of the message/metadata directly is
+          useful in scenarios when the message/metadata is very expensive to compute.
+          This is because the fun is only evaluted when the message/metadata is
+          actually needed, which may be not at all if the log event is not
+          to be logged. Examples:</p>
+        <code>
+%% A plain string with expensive metadata
+logger:info(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[]).
+%% An expensive report
+logger:debug(fun(What) -> #{ what => What, cause => expensive() } end,roof).
+%% A plain string with expensive metadata and normal metadata
+logger:debug(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[],
+             #{ meta => data }).
+        </code>
+        <p>When metadata is given both as an argument and returned from the fun they
+          are merged. If equal keys exists the values are taken from the metadata
+          returned by the fun.</p>
       </desc>
     </func>
   </funcs>
 
- 
   <funcs>
     <fsdescription>
       <marker id="configuration_API"/>
diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml
index b082607751..c2c70ce884 100644
--- a/lib/kernel/doc/src/logger_chapter.xml
+++ b/lib/kernel/doc/src/logger_chapter.xml
@@ -192,8 +192,18 @@
       <p>The log message contains the information to be logged. The
 	message can consist of a format string and arguments (given as
 	two separate parameters in the Logger API), a string or a
-	report. The latter, which is either a map or a key-value list,
-	can be accompanied by a <em>report callback</em> specified in
+        report.</p>
+      <p>Example, format string and arguments:</p>
+      <code>logger:error("The file does not exist: ~ts",[Filename])</code>
+      <p>Example, string:</p>
+      <code>logger:notice("Something strange happened!")</code>
+      <p>A report, which is either a map or a key-value list, is
+        the preferred way to log using Logger as it makes it possible
+        for different backends to filter and format the log event as it
+        needs to.</p>
+      <p>Example, report:</p>
+      <code>?LOG_ERROR(#{ user => joe, filename => Filename, reason => enoent })</code>
+      <p>Reports can be accompanied by a <em>report callback</em> specified in
 	the log event's <seeguide marker="#metadata">metadata</seeguide>.
 	The report callback is a convenience function that
 	the <seeguide marker="#formatters">formatter</seeguide> can use
@@ -219,10 +229,6 @@
 	contain line breaks or not. This variant is used when the
 	formatting of the report depends on the size or single line
 	parameters.</p>
-      <p>Example, format string and arguments:</p>
-      <code>logger:error("The file does not exist: ~ts",[Filename])</code>
-      <p>Example, string:</p>
-      <code>logger:notice("Something strange happened!")</code>
       <p>Example, report, and metadata with report callback:</p>
       <code>
 logger:debug(#{got => connection_request, id => Id, state => State},
-- 
2.26.2