From 97d14bf3dad4bb389beb646e25c0d822db1365e8 Mon Sep 17 00:00:00 2001
From: Klimov Paul <klimov.paul@gmail.com>
Date: Wed, 24 May 2017 13:14:19 +0300
Subject: [PATCH] `Logger` docs improved

---
 Logger.php | 44 ++++++++++++++++++++++++++++++++------------
 Mailer.php | 41 ++++++++++++++++++++++-------------------
 2 files changed, 54 insertions(+), 31 deletions(-)

diff --git a/Logger.php b/Logger.php
index c404822..646fd26 100644
--- a/Logger.php
+++ b/Logger.php
@@ -13,22 +13,44 @@ use Yii;
  * Logger is a SwiftMailer plugin, which allows passing of the SwiftMailer internal logs to the
  * Yii logging mechanism. Each native SwiftMailer log message will be converted into Yii 'info' log entry.
  *
+ * This logger will be automatically created and applied to underlying [[\Swift_Mailer]] instance, if [[Mailer::$enableSwiftMailerLogging]]
+ * is enabled. For example:
+ *
+ * ```php
+ * [
+ *     'components' => [
+ *         'mailer' => [
+ *             'class' => 'yii\swiftmailer\Mailer',
+ *             'enableSwiftMailerLogging' => true,
+ *         ],
+ *      ],
+ *     // ...
+ * ],
+ * ```
+ *
+ *
  * In order to catch logs written by this class, you need to setup a log route for 'yii\swiftmailer\Logger::add' category.
  * For example:
  *
- * ~~~
- * 'log' => [
- *     'targets' => [
- *         [
- *             'class' => 'yii\log\FileTarget',
- *             'categories' => ['yii\swiftmailer\Logger::add'],
+ * ```php
+ * [
+ *     'components' => [
+ *         'log' => [
+ *             'targets' => [
+ *                 [
+ *                     'class' => 'yii\log\FileTarget',
+ *                     'categories' => ['yii\swiftmailer\Logger::add'],
+ *                 ],
+ *             ],
  *         ],
+ *         // ...
  *     ],
+ *     // ...
  * ],
- * ~~~
+ * ```
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
- * @since 2.0
+ * @since 2.0.4
  */
 class Logger implements \Swift_Plugins_Logger
 {
@@ -49,10 +71,8 @@ class Logger implements \Swift_Plugins_Logger
             case '!!':
                 $level = \yii\log\Logger::LEVEL_WARNING;
                 break;
-        }
-
-        if (!isset($level)) {
-            $level = \yii\log\Logger::LEVEL_INFO;
+            default:
+                $level = \yii\log\Logger::LEVEL_INFO;
         }
 
         Yii::getLogger()->log($entry, $level, __METHOD__);
diff --git a/Mailer.php b/Mailer.php
index 3275511..5c92f53 100644
--- a/Mailer.php
+++ b/Mailer.php
@@ -14,25 +14,27 @@ use yii\mail\BaseMailer;
 /**
  * Mailer implements a mailer based on SwiftMailer.
  *
- * To use Mailer, you should configure it in the application configuration like the following,
+ * To use Mailer, you should configure it in the application configuration like the following:
  *
- * ~~~
- * 'components' => [
- *     ...
- *     'mailer' => [
- *         'class' => 'yii\swiftmailer\Mailer',
- *         'transport' => [
- *             'class' => 'Swift_SmtpTransport',
- *             'host' => 'localhost',
- *             'username' => 'username',
- *             'password' => 'password',
- *             'port' => '587',
- *             'encryption' => 'tls',
+ * ```php
+ * [
+ *     'components' => [
+ *         'mailer' => [
+ *             'class' => 'yii\swiftmailer\Mailer',
+ *             'transport' => [
+ *                 'class' => 'Swift_SmtpTransport',
+ *                 'host' => 'localhost',
+ *                 'username' => 'username',
+ *                 'password' => 'password',
+ *                 'port' => '587',
+ *                 'encryption' => 'tls',
+ *             ],
  *         ],
+ *         // ...
  *     ],
- *     ...
+ *     // ...
  * ],
- * ~~~
+ * ```
  *
  * You may also skip the configuration of the [[transport]] property. In that case, the default
  * PHP `mail()` function will be used to send emails.
@@ -41,7 +43,7 @@ use yii\mail\BaseMailer;
  * You can also specify the list of plugins, which should be registered to the transport using
  * 'plugins' key. For example:
  *
- * ~~~
+ * ```php
  * 'transport' => [
  *     'class' => 'Swift_SmtpTransport',
  *     'constructArgs' => ['localhost', 25]
@@ -52,17 +54,17 @@ use yii\mail\BaseMailer;
  *         ],
  *     ],
  * ],
- * ~~~
+ * ```
  *
  * To send an email, you may use the following code:
  *
- * ~~~
+ * ```php
  * Yii::$app->mailer->compose('contact/html', ['contactForm' => $form])
  *     ->setFrom('from@domain.com')
  *     ->setTo($form->email)
  *     ->setSubject($form->subject)
  *     ->send();
- * ~~~
+ * ```
  *
  * @see http://swiftmailer.org
  *
@@ -83,6 +85,7 @@ class Mailer extends BaseMailer
      * @var bool whether to enable writing of the SwiftMailer internal logs using Yii log mechanism.
      * If enabled [[Logger]] plugin will be attached to the [[transport]] for this purpose.
      * @see Logger
+     * @since 2.0.4
      */
     public $enableSwiftMailerLogging = false;