Update documentation of logger and error_logger

1 files changed, 193 insertions, 177 deletions

diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml
index ee43634cf9..02f89b26be 100644
--- a/lib/kernel/doc/src/logger_formatter.xml
+++ b/lib/kernel/doc/src/logger_formatter.xml
@@ -46,97 +46,150 @@
       Logger.</p>
   </description>
 
-  <section>
-    <title>Configuration</title>
-    <p>The configuration term for <c>logger_formatter</c> is a
-      <seealso marker="stdlib:maps">map</seealso>,
-      and the following keys can be set as configuration
-      parameters:</p>
-    <taglist>
-      <tag><c>chars_limit = pos_integer() | unlimited</c></tag>
-      <item>
-	<p>A positive integer representing the value of the option
-	  with the same name to be used when calling
-	  <seealso marker="stdlib:io_lib#format-3"><c>io_lib:format/3</c></seealso>.
-	  This value limits the total number of characters printed
-	  for each log event. Notice that this is a soft limit. For a
-	  hard truncation limit, see option <c>max_size</c>.</p>
-	<p>Default is <c>unlimited</c>.</p>
-	<note>
-	  <p><c>chars_limit</c> has no effect on log messages on
-	    string form. These are expected to be short, but can still
-	    be truncated by the <c>max_size</c> parameter.</p>
-	</note>
-      </item>
-      <tag><marker id="depth"/><c>depth = pos_integer() | unlimited</c></tag>
-      <item>
-	<p>A positive integer representing the maximum depth to
-	  which terms shall be printed by this formatter. Format
-	  strings passed to this formatter are rewritten. The format
-	  controls ~p and ~w are replaced with ~P and ~W,
-	  respectively, and the value is used as the depth
-	  parameter. For details, see
-	  <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
-	  in STDLIB.</p>
-	<p>Default is <c>unlimited</c>.</p>
-	<note>
-	  <p><c>depth</c> has no effect on log messages on string
-	    form. These are expected to be short, but can still be
-	    truncated by the <c>max_size</c> parameter.</p>
-	</note>
-      </item>
-      <tag><c>max_size = pos_integer() | unlimited</c></tag>
-      <item>
-	<p>A positive integer representing the absolute maximum size a
-	  string returned from this formatter can have. If the
-	  formatted string is longer, after possibly being limited
-	  by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p>
-	<p>Default is <c>unlimited</c>.</p>
-      </item>
-      <tag><c>single_line = boolean()</c></tag>
-      <item>
-	<p>If set to <c>true</c>, all newlines in the message are
-	  replaced with <c>", "</c>, and whitespaces following
-	  directly after newlines are removed. Note that newlines
-	  added by the <c>template</c> parameter are not replaced.</p>
-	<p>Default is <c>true</c>.</p>
-      </item>
-      <tag><c>legacy_header = boolean()</c></tag>
-      <item>
-	<p>If set to <c>true</c> a header field is added to
-	  logger_formatter's part of <c>Metadata</c>. The value of
-	  this field is a string similar to the header created by the
-	  old <c>error_logger</c> event handlers. It can be included
-	  in the log event by adding the
-	  tuple <c>{logger_formatter,header}</c> to the template. See
-	  section <seealso marker="#default_templates">Default
-	  Templates</seealso> for more information.</p>
-	<p>Default is <c>false</c>.</p>
-      </item>
-      <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>,[term()]})</c></tag>
-      <item>
-	<p>A report callback is used by the formatter to transform log
-	  messages on report form to a format string and
-	  arguments. The report callback can be specified in the
-	  metadata for the log event. If no report callback exist in
-	  metadata, <c>logger_formatter</c> will
-	  use <seealso marker="logger#format_report-1">
-	    <c>logger:format_report/1</c></seealso> as default
-	  callback.</p>
-	<p>If this configuration parameter is set, it replaces both
-	  the default report callback, and any report callback found
-	  in metadata. That is, all reports are converted by this
-	  configured function.</p>
-	<p>The value must be a function with arity 1,
-	  returning <c>{Format,Args}</c>, and it will be called with a
-	  report as only argument.</p>
-      </item>
-      <tag><c>template = </c><seealso marker="#type-template"><c>template()</c></seealso></tag>
-      <item>
+
+  <datatypes>
+    <datatype>
+      <name name="config"/>
+      <desc>
+	<p>The configuration term for <c>logger_formatter</c> is a
+	  <seealso marker="stdlib:maps">map</seealso>, and the
+	  following keys can be set as configuration parameters:</p>
+	<taglist>
+	  <tag><c>chars_limit = pos_integer() | unlimited</c></tag>
+	  <item>
+	    <p>A positive integer representing the value of the option
+	      with the same name to be used when calling
+	      <seealso marker="stdlib:io_lib#format-3">
+		<c>io_lib:format/3</c></seealso>.
+	      This value limits the total number of characters printed
+	      for each log event. Notice that this is a soft limit. For a
+	      hard truncation limit, see option <c>max_size</c>.</p>
+	    <p>Defaults to <c>unlimited</c>.</p>
+	    <note>
+	      <p><c>chars_limit</c> has no effect on log messages on
+		string form. These are expected to be short, but can
+		still be truncated by the <c>max_size</c>
+		parameter.</p>
+	    </note>
+	  </item>
+	  <tag><marker id="depth"/><c>depth = pos_integer() | unlimited</c></tag>
+	  <item>
+	    <p>A positive integer representing the maximum depth to
+	      which terms shall be printed by this formatter. Format
+	      strings passed to this formatter are rewritten. The
+	      format controls ~p and ~w are replaced with ~P and ~W,
+	      respectively, and the value is used as the depth
+	      parameter. For details, see
+	      <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
+	      in STDLIB.</p>
+	    <p>Defaults to <c>unlimited</c>.</p>
+	    <note>
+	      <p><c>depth</c> has no effect on log messages on string
+		form. These are expected to be short, but can still be
+		truncated by the <c>max_size</c> parameter.</p>
+	    </note>
+	  </item>
+	  <tag><c>legacy_header = boolean()</c></tag>
+	  <item>
+	    <p>If set to <c>true</c> a header field is added to
+	      logger_formatter's part of <c>Metadata</c>. The value of
+	      this field is a string similar to the header created by
+	      the old <c>error_logger</c> event handlers. It can be
+	      included in the log event by adding the
+	      tuple <c>{logger_formatter,header}</c> to the
+	      template. See the description of
+	      the <seealso marker="#type-template"><c>template()</c></seealso>
+	      type for more information.</p>
+	    <p>Defaults to <c>false</c>.</p>
+	  </item>
+	  <tag><c>max_size = pos_integer() | unlimited</c></tag>
+	  <item>
+	    <p>A positive integer representing the absolute maximum size a
+	      string returned from this formatter can have. If the
+	      formatted string is longer, after possibly being limited
+	      by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p>
+	    <p>Defaults to <c>unlimited</c>.</p>
+	  </item>
+	  <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>,[term()]})</c></tag>
+	  <item>
+	    <p>A report callback is used by the formatter to transform
+	      log messages on report form to a format string and
+	      arguments. The report callback can be specified in the
+	      metadata for the log event. If no report callback exist
+	      in metadata, <c>logger_formatter</c> will
+	      use <seealso marker="logger#format_report-1">
+		<c>logger:format_report/1</c></seealso> as default
+	      callback.</p>
+	    <p>If this configuration parameter is set, it replaces
+	      both the default report callback, and any report
+	      callback found in metadata. That is, all reports are
+	      converted by this configured function.</p>
+	    <p>The value must be a function with arity 1,
+	      returning <c>{Format,Args}</c>, and it will be called
+	      with a report as only argument.</p>
+	  </item>
+	  <tag><c>single_line = boolean()</c></tag>
+	  <item>
+	    <p>If set to <c>true</c>, all newlines in the message are
+	      replaced with <c>", "</c>, and whitespaces following
+	      directly after newlines are removed. Note that newlines
+	      added by the <c>template</c> parameter are not replaced.</p>
+	    <p>Defaults to <c>true</c>.</p>
+	  </item>
+	  <tag><c>template = </c><seealso marker="#type-template"><c>template()</c></seealso></tag>
+	  <item>
+	    <p>The template describes how the formatted string is
+	      composed by combining different data values from the log
+	      event. See the description of
+	      the <seealso marker="#type-template"><c>template()</c></seealso>
+	      type for more information about this.</p>
+	  </item>
+	  <tag><c>time_designator = byte()</c></tag>
+	  <item>
+	    <p>Timestamps are formatted according to RFC3339, and the
+	      time designator is the character used as date and time
+	      separator.</p>
+	    <p>Defaults to <c>$T</c>.</p>
+	    <p>The value of this parameter is used as
+	      the <c>time_designator</c> option
+	      to <seealso marker="stdlib:calendar#system_time_to_rfc3339-2">
+		<c>calendar:system_time_to_rcf3339/2</c></seealso>.</p>
+	  </item>
+	  <tag><c>time_offset = integer() | [byte()]</c></tag>
+	  <item>
+	    <p>The time offset, either a string or an integer, to be
+	      used when formatting the timestamp.</p>
+	    <p>An empty string is interpreted as local time. The
+	      values <c>"Z"</c>, <c>"z"</c> or <c>0</c> are
+	      interpreted as Universal Coordinated Time (UTC).</p>
+	    <p>Strings, other than <c>"Z"</c>, <c>"z"</c>,
+	      or <c>""</c>, must be on the form <c>±[hh]:[mm]</c>, for
+	      example <c>"-02:00"</c> or <c>"+00:00"</c>.</p>
+	    <p>Integers must be in microseconds, meaning that the
+	      offset <c>7200000000</c> is equivalent
+	      to <c>"+02:00"</c>.</p>
+	    <p>Defaults to an empty string, meaning that timestamps
+	      are displayed in local time. However, for backwards
+	      compatibility, if the SASL configuration
+	      parameter <seealso marker="sasl:sasl_app#utc_log">
+		<c>utc_log</c></seealso><c>=true</c>, the default is
+	      changed to <c>"Z"</c>, meaning that timestamps are displayed
+	      in UTC.</p>
+	    <p>The value of this parameter is used as
+	      the <c>offset</c> option
+	      to <seealso marker="stdlib:calendar#system_time_to_rfc3339-2">
+		<c>calendar:system_time_to_rcf3339/2</c></seealso>.</p>
+	  </item>
+	</taglist>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="template"/>
+      <desc>
 	<p>The template is a list of atoms, tuples and strings. The
 	  atoms <c>level</c> or <c>msg</c>, are treated as
 	  placeholders for the severity level and the log message,
-	  repectively. Other atoms or tuples are interpreted as
+	  respectively. Other atoms or tuples are interpreted as
 	  placeholders for metadata, where atoms are expected to match
 	  top level keys, and tuples represent paths to sub keys when
 	  the metadata is a nested map. For example the
@@ -154,121 +207,85 @@
         <p>Strings in the template are printed literally.</p>
 	<p>The default template differs depending on the values
 	  of <c>legacy_header</c>
-	  and <c>single_line</c>. See <seealso marker="#default_templates">Default
-	  Templates</seealso> for more information</p>
-      </item>
-      <tag><c>time_designator = byte()</c></tag>
-      <item>
-	<p>Timestamps are formatted according to RFC3339, and the time
-	  designator is the character used as date and time
-	  separator.</p>
-	<p>Default is <c>$T</c>.</p>
-	<p>The value of this parameter is used as
-	  the <c>time_designator</c> option
-	  to <seealso marker="stdlib:calendar#system_time_to_rfc3339-2">
-	    <c>calendar:system_time_to_rcf3339/2</c></seealso>.</p>
-      </item>
-      <tag><c>time_offset = integer() | [byte()]</c></tag>
-      <item>
-	<p>The time offset, either a string or an integer, to be
-	  used when formatting the timestamp.</p>
-	<p>An empty string is interpreted as local time. The
-	  values <c>"Z"</c>, <c>"z"</c> or <c>0</c> are interpreted as
-	  Universal Coordinated Time (UTC).</p>
-	<p>Strings, other than <c>"Z"</c>, <c>"z"</c>, or <c>""</c>,
-	  must be on the form <c>±[hh]:[mm]</c>, for
-	  example <c>"-02:00"</c> or <c>"+00:00"</c>.</p>
-	<p>Integers must be in microseconds, meaning that the
-	  offset <c>7200000000</c> is equivalent
-	  to <c>"+02:00"</c>.</p>
-	<p>The default value is an empty string, meaning that
-	  timestamps are displayed in local time. However, for
-	  backwards compatibility, if the SASL configuration
-	  parameter <seealso marker="sasl:sasl_app#utc_log">
-	    <c>utc_log</c></seealso><c>=true</c>, the default is
-	  changed to <c>"Z"</c>, meaning that timestamps are displayed
-	  in UTC.</p>
-	<p>The value of this parameter is used as the <c>offset</c>
-	  option to <seealso marker="stdlib:calendar#system_time_to_rfc3339-2">
-	    <c>calendar:system_time_to_rcf3339/2</c></seealso>.</p>
-      </item>
-    </taglist>
-  </section>
-
-  <section>
-    <marker id="default_templates"/>
-    <title>Default templates</title>
+	  and <c>single_line</c>:</p>
 
-    <p>The default value for the <c>template</c> configuration
-      parameter depends on the value of <c>single_line</c>
-      and <c>legacy_header</c> as follows.</p>
+	<p>The default value for the <c>template</c> configuration
+	  parameter depends on the value of the <c>single_line</c>
+	  and <c>legacy_header</c> configuration parameters as
+	  follows.</p>
 
-    <p>The log event used in the examples is:</p>
-    <code>
+	<p>The log event used in the examples is:</p>
+	<code>
 ?LOG_ERROR("name: ~p~nexit_reason: ~p",[my_name,"It crashed"])</code>
 
-    <taglist>
-      <tag><c>legacy_header=true, single_line=false</c></tag>
-      <item>
-	<p>Default template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p>
+	<taglist>
+	  <tag><c>legacy_header=true, single_line=false</c></tag>
+	  <item>
+	    <p>Default
+	    template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p>
 
-	<p>Example log entry:</p>
-	<code type="none">
+	    <p>Example log entry:</p>
+	    <code type="none">
 =ERROR REPORT==== 17-May-2018::18:30:19.453447 ===
 name: my_name
 exit_reason: "It crashed"</code>
 
-	<p>Notice that all eight levels can occur in the heading,
-	  not only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c> as the
-	  old <c>error_logger</c> produced. And microseconds are
-	  added at the end of the timestamp.</p>
-      </item>
+	    <p>Notice that all eight levels can occur in the heading,
+	      not only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c> as the
+	      old <c>error_logger</c> produced. And microseconds are
+	      added at the end of the timestamp.</p>
+	  </item>
 
-      <tag><c>legacy_header=true, single_line=true</c></tag>
-      <item>
-	<p>Default template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p>
+	  <tag><c>legacy_header=true, single_line=true</c></tag>
+	  <item>
+	    <p>Default
+	    template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p>
 
-	<p>Notice that the template is here the same as
-	  for <c>single_line=false</c>, but the resulting log entry
-	  differs in that there is only one line after the
-	  heading:</p>
-	<code type="none">
+	    <p>Notice that the template is here the same as
+	      for <c>single_line=false</c>, but the resulting log entry
+	      differs in that there is only one line after the
+	      heading:</p>
+	    <code type="none">
 =ERROR REPORT==== 17-May-2018::18:31:06.952665 ===
 name: my_name, exit_reason: "It crashed"</code>
-      </item>
+	  </item>
 
-      <tag><c>legacy_header=false, single_line=true</c></tag>
-      <item>
-	<p>Default template: <c>[time," ",level,": ",msg,"\n"]</c></p>
+	  <tag><c>legacy_header=false, single_line=true</c></tag>
+	  <item>
+	    <p>Default template: <c>[time," ",level,": ",msg,"\n"]</c></p>
 
-	<p>Example log entry:</p>
-	<code type="none">
+	    <p>Example log entry:</p>
+	    <code type="none">
 2018-05-17T18:31:31.152864+02:00 error: name: my_name, exit_reason: "It crashed"</code>
-      </item>
+	  </item>
 
-      <tag><c>legacy_header=false, single_line=false</c></tag>
-      <item>
-	<p>Default template: <c>[time," ",level,":\n",msg,"\n"]</c></p>
+	  <tag><c>legacy_header=false, single_line=false</c></tag>
+	  <item>
+	    <p>Default template: <c>[time," ",level,":\n",msg,"\n"]</c></p>
 
-	<p>Example log entry:</p>
-	<code type="none">
+	    <p>Example log entry:</p>
+	    <code type="none">
 2018-05-17T18:32:20.105422+02:00 error:
 name: my_name
 exit_reason: "It crashed"</code>
-      </item>
-    </taglist>
-  </section>
-
-  <datatypes>
-    <datatype>
-      <name name="template"/>
-      <desc>
+	  </item>
+	</taglist>
       </desc>
     </datatype>
   </datatypes>
 
   <funcs>
     <func>
+      <name name="check_config" arity="1"/>
+      <fsummary>Validates the given formatter configuration.</fsummary>
+      <desc>
+	<p>This callback function is called by Logger when the
+	  formatter configuration for a handler is set or modified. It
+	  returns <c>ok</c> if the configuration is valid,
+	  and <c>{error,term()}</c> if it is faulty.</p>
+      </desc>
+    </func>
+    <func>
       <name name="format" arity="2"/>
       <fsummary>Formats the given message.</fsummary>
       <desc>
@@ -290,7 +307,6 @@ exit_reason: "It crashed"</code>
 	</list>
       </desc>
     </func>
-
   </funcs>
 
 </erlref>