   @doc """
   Adds a new backend.
 
+  Adding a backend calls the `init/1` function in that backend
+  with the name of the backend as its argument. For example,
+  calling
+
+      Logger.add_backend(MyBackend)
+
+  will call `MyBackend.init(MyBackend)` to initialize the new
+  backend. If the backend's `init/1` callback returns `{:ok, _}`,
+  then this function returns `{:ok, pid}`. If the handler returns
+  `{:error, :ignore}` from `init/1`, this function still returns
+  `{:ok, pid}` but the handler is not started. If the handler
+  returns `{:error, reason}` from `init/1`, this function returns
+  `{:error, {reason, info}}` where `info` is more information on
+  the backend that failed to start.
+
   Backends added by this function are not persisted. Therefore
   if the Logger application or supervision tree is restarted,
   the backend won't be available. If you need this guarantee,
-  then configure the backend via the application environment.
+  then configure the backend via the application environment:
+
+      config :logger, :backends, [MyBackend]
 
   ## Options
 
     * `:flush` - when `true`, guarantees all messages currently sent
       to `Logger` are processed before the backend is added
+
+  ## Examples
+
+      {:ok, _pid} = Logger.add_backend(MyBackend, flush: true)
 
   """
   @spec add_backend(backend, keyword) :: Supervisor.on_start_child()


  where `options` is a keyword list. The result of the call is
  the result returned by `configure_backend/2`. The recommended
  return value for successful configuration is `:ok`.

  It is recommended that backends support at least the following
  configuration options:


  The initial backends are loaded via the `:backends` configuration,
  which must be set before the `:logger` application is started.
  Backends can also be added dynamically through `add_backend/2`.

  ### Console backend

