diff --git a/homeassistant/components/switch/mqtt.py b/homeassistant/components/switch/mqtt.py
index 73618bd9277..b8a550dba70 100644
--- a/homeassistant/components/switch/mqtt.py
+++ b/homeassistant/components/switch/mqtt.py
@@ -1,70 +1,11 @@
-# -*- coding: utf-8 -*-
 """
 homeassistant.components.switch.mqtt
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Allows to configure a MQTT switch.
 
-In an ideal scenario, the MQTT device will have a state topic to publish
-state changes. If these messages are published with RETAIN flag, the MQTT
-switch will receive an instant state update after subscription and will
-start with correct state. Otherwise, the initial state of the switch will
-be false/off.
-
-When a state topic is not available, the switch will work in optimistic mode.
-In this mode, the switch will immediately change state after every command.
-Otherwise, the switch will wait for state confirmation from device
-(message from state_topic).
-
-Optimistic mode can be forced, even if state topic is available.
-Try to enable it, if experiencing incorrect switch operation.
-
-
-Configuration:
-
-switch:
-  platform: mqtt
-  name: "Bedroom Switch"
-  state_topic: "home/bedroom/switch1"
-  command_topic: "home/bedroom/switch1/set"
-  qos: 0
-  payload_on: "ON"
-  payload_off: "OFF"
-  optimistic: false
-
-Variables:
-
-name
-*Optional
-The name of the switch. Default is 'MQTT Switch'.
-
-state_topic
-*Optional
-The MQTT topic subscribed to receive state updates.
-If not specified, optimistic mode will be forced.
-
-command_topic
-*Required
-The MQTT topic to publish commands to change the switch state.
-
-qos
-*Optional
-The maximum QoS level of the state topic. Default is 0.
-This QoS will also be used to publishing messages.
-
-payload_on
-*Optional
-The payload that represents enabled state. Default is "ON".
-
-payload_off
-*Optional
-The payload that represents disabled state. Default is "OFF".
-
-optimistic
-*Optional
-Flag that defines if switch works in optimistic mode. Default is false.
-
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/switch.mqtt.html
 """
-
 import logging
 import homeassistant.components.mqtt as mqtt
 from homeassistant.components.switch import SwitchDevice
@@ -82,7 +23,7 @@ DEPENDENCIES = ['mqtt']
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Add MQTT Switch """
+    """ Add MQTT Switch. """
 
     if config.get('command_topic') is None:
         _LOGGER.error("Missing required variable: command_topic")
@@ -101,7 +42,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 # pylint: disable=too-many-arguments, too-many-instance-attributes
 class MqttSwitch(SwitchDevice):
-    """ Represents a switch that can be togggled using MQTT """
+    """ Represents a switch that can be togggled using MQTT. """
     def __init__(self, hass, name, state_topic, command_topic, qos,
                  payload_on, payload_off, optimistic):
         self._state = False
@@ -133,12 +74,12 @@ class MqttSwitch(SwitchDevice):
 
     @property
     def should_poll(self):
-        """ No polling needed """
+        """ No polling needed. """
         return False
 
     @property
     def name(self):
-        """ The name of the switch """
+        """ The name of the switch. """
         return self._name
 
     @property