Move custom formatting docs to Logger.Formatter

3 files changed, 57 insertions, 52 deletions

diff --git a/lib/logger/lib/logger.ex b/lib/logger/lib/logger.ex
index 9a90ebcab..9e25a197f 100644
--- a/lib/logger/lib/logger.ex
+++ b/lib/logger/lib/logger.ex
@@ -311,7 +311,8 @@ defmodule Logger do
   The available backends by default are:
 
     * `:console` - logs messages to the console (enabled by default).
-      `:console` is simply a shortcut for `Logger.Backends.Console`.
+      `:console` is simply a shortcut for `Logger.Backends.Console`
+      (see its documentation for more information)
 
   Developers may also implement their own backends, an option that
   is explored in more detail below.
diff --git a/lib/logger/lib/logger/backends/console.ex b/lib/logger/lib/logger/backends/console.ex
index ad67d1092..0ffa5982f 100644
--- a/lib/logger/lib/logger/backends/console.ex
+++ b/lib/logger/lib/logger/backends/console.ex
@@ -12,7 +12,7 @@ defmodule Logger.Backends.Console do
       Defaults to: `"\n$time $metadata[$level] $message\n"`.
       It may also be a `{module, function}` tuple that is invoked
       with the log level, the message, the current timestamp and
-      the metadata.
+      the metadata. See `Logger.Formatter`.
 
     * `:metadata` - the metadata to be printed by `$metadata`.
       Defaults to an empty list (no metadata).
@@ -51,52 +51,6 @@ defmodule Logger.Backends.Console do
         format: "\n$time $metadata[$level] $message\n",
         metadata: [:user_id]
 
-  ## Custom formatting
-
-  The console backend allows you to customize the format of your
-  log messages with the `:format` option.
-
-  You may set `:format` to either a string or a `{module, function}`
-  tuple if you wish to provide your own format function. Here is an
-  example of how to configure the `:console` backend in a
-  `config/config.exs` file:
-
-      config :logger, :console,
-        format: {MyConsoleLogger, :format}
-
-  And here is an example of how you can define `MyConsoleLogger.format/4`
-  from the above configuration:
-
-      defmodule MyConsoleLogger do
-        def format(level, message, timestamp, metadata) do
-          # Custom formatting logic...
-        end
-      end
-
-  It is extremely important that **the formatting function does
-  not fail**, as it will bring that particular logger instance down,
-  causing your system to temporarily lose messages. If necessary,
-  wrap the function in a `rescue` and log a default message instead:
-
-      defmodule MyConsoleLogger do
-        def format(level, message, timestamp, metadata) do
-          # Custom formatting logic...
-        rescue
-          _ -> "could not format: #{inspect({level, message, metadata})}"
-        end
-      end
-
-  The `{module, function}` will be invoked with four arguments:
-
-    * the log level: an atom
-    * the message: this is usually chardata, but in some cases it
-      may contain invalid data. Since the formatting function should
-      *never* fail, you need to prepare for the message being anything
-    * the current timestamp: a term of type `t:Logger.Formatter.time/0`
-    * the metadata: a keyword list
-
-  You can read more about formatting in `Logger.Formatter`, especially
-  if you want to support custom formatting in a custom backend.
   """
 
   @behaviour :gen_event
diff --git a/lib/logger/lib/logger/formatter.ex b/lib/logger/lib/logger/formatter.ex
index fa7f93f03..431cc226e 100644
--- a/lib/logger/lib/logger/formatter.ex
+++ b/lib/logger/lib/logger/formatter.ex
@@ -4,12 +4,21 @@ defmodule Logger.Formatter do
   @moduledoc ~S"""
   Conveniences for formatting data for logs.
 
-  This module allows developers to specify a string that
-  serves as template for log messages, for example:
+  This module allows developers to specify a `{module, function}`
+  or a string that serves as template for log messages.
 
-      $time $metadata[$level] $message\n
+  ## Formatting string
 
-  Will print error messages as:
+  The log messages can be controlled by a formatting string.
+  Here is an example of how to configure the `:console` backend
+  in a `config/config.exs` file:
+
+  For example:
+
+      config :logger, :console,
+        format: "$time $metadata[$level] $message\n"
+
+  The above will print error messages as:
 
       18:43:12.439 user_id=13 [error] Hello\n
 
@@ -28,6 +37,47 @@ defmodule Logger.Formatter do
   runtime and `format/5` to format the compiled pattern into an
   actual IO data.
 
+  ## Formatting function
+
+  You can also customize the format of your log messages to a
+  `{module, function}` tuple if you wish to provide your own
+  format function. Here is an example of how to configure the
+  `:console` backend in a `config/config.exs` file:
+
+      config :logger, :console,
+        format: {MyConsoleLogger, :format}
+
+  And here is an example of how you can define `MyConsoleLogger.format/4`
+  from the above configuration:
+
+      defmodule MyConsoleLogger do
+        def format(level, message, timestamp, metadata) do
+          # Custom formatting logic...
+        end
+      end
+
+  It is extremely important that **the formatting function does
+  not fail**, as it will bring that particular logger instance down,
+  causing your system to temporarily lose messages. If necessary,
+  wrap the function in a `rescue` and log a default message instead:
+
+      defmodule MyConsoleLogger do
+        def format(level, message, timestamp, metadata) do
+          # Custom formatting logic...
+        rescue
+          _ -> "could not format: #{inspect({level, message, metadata})}"
+        end
+      end
+
+  The `{module, function}` will be invoked with four arguments:
+
+    * the log level: an atom
+    * the message: this is usually chardata, but in some cases it
+      may contain invalid data. Since the formatting function should
+      *never* fail, you need to prepare for the message being anything
+    * the current timestamp: a term of type `t:time/0`
+    * the metadata: a keyword list
+
   ## Metadata
 
   Metadata to be sent to the logger can be read and written with