Docstrings (#2395)

* Replace switch with lock

* Update docstrings

* Add link to docs

* Add link to docs and update docstrings

* Update docstring

* Update docstrings and fix typos

* Add link to docs

* Add link to docs

* Add link to docs and update docstrings

* Fix link to docs and update docstrings

* Remove blank line

* Add link to docs

homeassistant/components/binary_sensor/homematic.py

@@ -1,13 +1,9 @@
 """
-The homematic binary sensor platform.
+Support for Homematic binary sensors.
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/binary_sensor.homematic/
-
-Important: For this platform to work the homematic component has to be
-properly configured.
 """
-
 import logging
 from homeassistant.const import STATE_UNKNOWN
 from homeassistant.components.binary_sensor import BinarySensorDevice
@@ -29,7 +25,7 @@ SENSOR_TYPES_CLASS = {
 
 
 def setup_platform(hass, config, add_callback_devices, discovery_info=None):
-    """Setup the platform."""
+    """Setup the Homematic binary sensor platform."""
     if discovery_info is None:
         return
 
@@ -39,11 +35,11 @@ def setup_platform(hass, config, add_callback_devices, discovery_info=None):
 
 
 class HMBinarySensor(homematic.HMDevice, BinarySensorDevice):
-    """Represents diverse binary Homematic units in Home Assistant."""
+    """Representation of a binary Homematic device."""
 
     @property
     def is_on(self):
-        """Return True if switch is on."""
+        """Return true if switch is on."""
         if not self.available:
             return False
         return bool(self._hm_get_state())
@@ -68,20 +64,20 @@ class HMBinarySensor(homematic.HMDevice, BinarySensorDevice):
         if not super()._check_hm_to_ha_object():
             return False
 
-        # check if the homematic device correct for this HA device
+        # check if the Homematic device correct for this HA device
         if not isinstance(self._hmdevice, pyHMBinarySensor):
-            _LOGGER.critical("This %s can't be use as binary!", self._name)
+            _LOGGER.critical("This %s can't be use as binary", self._name)
             return False
 
         # if exists user value?
         if self._state and self._state not in self._hmdevice.BINARYNODE:
-            _LOGGER.critical("This %s have no binary with %s!", self._name,
+            _LOGGER.critical("This %s have no binary with %s", self._name,
                              self._state)
             return False
 
-        # only check and give a warining to User
+        # only check and give a warning to the user
         if self._state is None and len(self._hmdevice.BINARYNODE) > 1:
-            _LOGGER.critical("%s have multible binary params. It use all " +
+            _LOGGER.critical("%s have multiple binary params. It use all "
                              "binary nodes as one. Possible param values: %s",
                              self._name, str(self._hmdevice.BINARYNODE))
             return False
@@ -89,7 +85,7 @@ class HMBinarySensor(homematic.HMDevice, BinarySensorDevice):
         return True
 
     def _init_data_struct(self):
-        """Generate a data struct (self._data) from hm metadata."""
+        """Generate a data struct (self._data) from the Homematic metadata."""
         super()._init_data_struct()
 
         # object have 1 binary

homeassistant/components/camera/rpi_camera.py

@@ -1,5 +1,9 @@
-"""Camera platform that has a Raspberry Pi camera."""
+"""
+Camera platform that has a Raspberry Pi camera.
 
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/camera.rpi_camera/
+"""
 import os
 import subprocess
 import logging
@@ -43,7 +47,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 
 class RaspberryCamera(Camera):
-    """Raspberry Pi camera."""
+    """Representation of a Raspberry Pi camera."""
 
     def __init__(self, device_info):
         """Initialize Raspberry Pi camera component."""

homeassistant/components/homematic.py

@@ -1,16 +1,8 @@
 """
-Support for Homematic Devices.
+Support for Homematic devices.
 
 For more details about this component, please refer to the documentation at
 https://home-assistant.io/components/homematic/
-
-Configuration:
-
-homematic:
-  local_ip: "<IP of device running Home Assistant>"
-  local_port: <Port for connection with Home Assistant>
-  remote_ip: "<IP of Homegear / CCU>"
-  remote_port: <Port of Homegear / CCU XML-RPC Server>
 """
 import time
 import logging
@@ -170,7 +162,7 @@ def system_callback_handler(hass, config, src, *args):
 
 
 def _get_devices(device_type, keys):
-    """Get devices."""
+    """Get the Homematic devices."""
     # run
     device_arr = []
     for key in keys:
@@ -320,11 +312,11 @@ def _hm_event_handler(hass, device, caller, attribute, value):
 
 
 class HMDevice(Entity):
-    """Homematic device base object."""
+    """The Homematic device base object."""
 
     # pylint: disable=too-many-instance-attributes
     def __init__(self, config):
-        """Initialize generic HM device."""
+        """Initialize a generic Homematic device."""
         self._name = config.get(ATTR_NAME, None)
         self._address = config.get(ATTR_ADDRESS, None)
         self._channel = config.get(ATTR_CHANNEL, 1)
@@ -346,7 +338,7 @@ class HMDevice(Entity):
 
     @property
     def should_poll(self):
-        """Return False. Homematic states are pushed by the XML RPC Server."""
+        """Return false. Homematic states are pushed by the XML RPC Server."""
         return False
 
     @property
@@ -356,12 +348,12 @@ class HMDevice(Entity):
 
     @property
     def assumed_state(self):
-        """Return True if unable to access real state of the device."""
+        """Return true if unable to access real state of the device."""
         return not self._available
 
     @property
     def available(self):
-        """Return True if device is available."""
+        """Return true if device is available."""
         return self._available
 
     @property
@@ -386,7 +378,7 @@ class HMDevice(Entity):
         return attr
 
     def link_homematic(self):
-        """Connect to homematic."""
+        """Connect to Homematic."""
         # device is already linked
         if self._connected:
             return True
@@ -397,7 +389,7 @@ class HMDevice(Entity):
             self._hmdevice = HOMEMATIC.devices[self._address]
             self._connected = True
 
-            # Check if HM class is okay for HA class
+            # Check if Homematic class is okay for HA class
             _LOGGER.info("Start linking %s to %s", self._address, self._name)
             if self._check_hm_to_ha_object():
                 try:
@@ -420,7 +412,7 @@ class HMDevice(Entity):
                     _LOGGER.error("Exception while linking %s: %s",
                                   self._address, str(err))
             else:
-                _LOGGER.critical("Delink %s object from HM!", self._name)
+                _LOGGER.critical("Delink %s object from HM", self._name)
                 self._connected = False
 
             # Update HA
@@ -514,7 +506,7 @@ class HMDevice(Entity):
         return None
 
     def _check_hm_to_ha_object(self):
-        """Check if it is possible to use the HM Object as this HA type.
+        """Check if it is possible to use the Homematic object as this HA type.
 
         NEEDS overwrite by inherit!
         """
@@ -530,7 +522,7 @@ class HMDevice(Entity):
         return True
 
     def _init_data_struct(self):
-        """Generate a data dict (self._data) from hm metadata.
+        """Generate a data dict (self._data) from the Homematic metadata.
 
         NEEDS overwrite by inherit!
         """

homeassistant/components/light/enocean.py

@@ -4,7 +4,6 @@ Support for EnOcean light sources.
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/light.enocean/
 """
-
 import logging
 import math
 
@@ -86,7 +85,7 @@ class EnOceanLight(enocean.EnOceanDevice, Light):
         self._on_state = False
 
     def value_changed(self, val):
-        """Update the internal state of this device in HA."""
+        """Update the internal state of this device."""
         self._brightness = math.floor(val / 100.0 * 256.0)
         self._on_state = bool(val != 0)
         self.update_ha_state()

homeassistant/components/light/homematic.py

@@ -1,13 +1,9 @@
 """
-The homematic light platform.
+Support for Homematic lighs.
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/light.homematic/
-
-Important: For this platform to work the homematic component has to be
-properly configured.
 """
-
 import logging
 from homeassistant.components.light import (ATTR_BRIGHTNESS, Light)
 from homeassistant.const import STATE_UNKNOWN
@@ -15,12 +11,11 @@ import homeassistant.components.homematic as homematic
 
 _LOGGER = logging.getLogger(__name__)
 
-# List of component names (string) your component depends upon.
 DEPENDENCIES = ['homematic']
 
 
 def setup_platform(hass, config, add_callback_devices, discovery_info=None):
-    """Setup the platform."""
+    """Setup the Homematic light platform."""
     if discovery_info is None:
         return
 
@@ -30,7 +25,7 @@ def setup_platform(hass, config, add_callback_devices, discovery_info=None):
 
 
 class HMLight(homematic.HMDevice, Light):
-    """Represents a Homematic Light in Home Assistant."""
+    """Representation of a Homematic light."""
 
     @property
     def brightness(self):
@@ -45,7 +40,7 @@ class HMLight(homematic.HMDevice, Light):
 
     @property
     def is_on(self):
-        """Return True if light is on."""
+        """Return true if light is on."""
         try:
             return self._hm_get_state() > 0
         except TypeError:
@@ -68,24 +63,24 @@ class HMLight(homematic.HMDevice, Light):
             self._hmdevice.off(self._channel)
 
     def _check_hm_to_ha_object(self):
-        """Check if possible to use the HM Object as this HA type."""
+        """Check if possible to use the Homematic object as this HA type."""
         from pyhomematic.devicetypes.actors import Dimmer, Switch
 
         # Check compatibility from HMDevice
         if not super()._check_hm_to_ha_object():
             return False
 
-        # Check if the homematic device is correct for this HA device
+        # Check if the Homematic device is correct for this HA device
         if isinstance(self._hmdevice, Switch):
             return True
         if isinstance(self._hmdevice, Dimmer):
             return True
 
-        _LOGGER.critical("This %s can't be use as light!", self._name)
+        _LOGGER.critical("This %s can't be use as light", self._name)
         return False
 
     def _init_data_struct(self):
-        """Generate a data dict (self._data) from hm metadata."""
+        """Generate a data dict (self._data) from the Homematic metadata."""
         from pyhomematic.devicetypes.actors import Dimmer, Switch
 
         super()._init_data_struct()

homeassistant/components/light/osramlightify.py

@@ -1,19 +1,9 @@
 """
 Support for Osram Lightify.
 
-Uses: https://github.com/aneumeier/python-lightify for the Osram light
-interface.
-
-In order to use the platform just add the following to the configuration.yaml:
-
-light:
-  platform: osramlightify
-  host: <hostname_or_ip>
-
-Todo:
-Add support for Non RGBW lights.
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/light.osramlightify/
 """
-
 import logging
 import socket
 from datetime import timedelta
@@ -40,7 +30,7 @@ MIN_TIME_BETWEEN_FORCED_SCANS = timedelta(milliseconds=100)
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """Find and return lights."""
+    """Setup Osram Lightify lights."""
     import lightify
     host = config.get(CONF_HOST)
     if host:
@@ -85,7 +75,7 @@ def setup_bridge(bridge, add_devices_callback):
 
 
 class OsramLightifyLight(Light):
-    """Defines an Osram Lightify Light."""
+    """Representation of an Osram Lightify Light."""
 
     def __init__(self, light_id, light, update_lights):
         """Initialize the light."""

homeassistant/components/lock/vera.py

@@ -18,14 +18,14 @@ _LOGGER = logging.getLogger(__name__)
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """Find and return Vera switches."""
+    """Find and return Vera locks."""
     add_devices_callback(
         VeraLock(device, VERA_CONTROLLER) for
         device in VERA_DEVICES['lock'])
 
 
 class VeraLock(VeraDevice, LockDevice):
-    """Representation of a Vera Lock."""
+    """Representation of a Vera lock."""
 
     def __init__(self, vera_device, controller):
         """Initialize the Vera device."""
@@ -43,13 +43,13 @@ class VeraLock(VeraDevice, LockDevice):
         return attr
 
     def lock(self, **kwargs):
-        """Lock."""
+        """Lock the device."""
         self.vera_device.lock()
         self._state = STATE_LOCKED
         self.update_ha_state()
 
     def unlock(self, **kwargs):
-        """Unlock."""
+        """Unlock the device."""
         self.vera_device.unlock()
         self._state = STATE_UNLOCKED
         self.update_ha_state()
@@ -60,6 +60,6 @@ class VeraLock(VeraDevice, LockDevice):
         return self._state == STATE_LOCKED
 
     def update(self):
-        """Called by the vera device callback to update state."""
+        """Called by the Vera device callback to update state."""
         self._state = (STATE_LOCKED if self.vera_device.is_locked(True)
                        else STATE_UNLOCKED)

homeassistant/components/media_player/braviatv.py

@@ -1,10 +1,8 @@
 """
 Support for interface with a Sony Bravia TV.
 
-By Antonio Parraga Navarro
-
-dedicated to Isabel
-
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/media_player.braviatv/
 """
 import logging
 import os
@@ -38,6 +36,7 @@ SUPPORT_BRAVIA = SUPPORT_PAUSE | SUPPORT_VOLUME_STEP | \
 
 
 def _get_mac_address(ip_address):
+    """Get the MAC address of the device."""
     from subprocess import Popen, PIPE
 
     pid = Popen(["arp", "-n", ip_address], stdout=PIPE)
@@ -48,7 +47,7 @@ def _get_mac_address(ip_address):
 
 
 def _config_from_file(filename, config=None):
-    """Small configuration file management function."""
+    """Create the configuration from a file."""
     if config:
         # We're writing configuration
         bravia_config = _config_from_file(filename)
@@ -104,7 +103,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 # pylint: disable=too-many-branches
 def setup_bravia(config, pin, hass, add_devices_callback):
-    """Setup a sony bravia based on host parameter."""
+    """Setup a Sony Bravia TV based on host parameter."""
     host = config.get(CONF_HOST)
     name = config.get(CONF_NAME)
     if name is None:
@@ -176,7 +175,7 @@ class BraviaTVDevice(MediaPlayerDevice):
     """Representation of a Sony Bravia TV."""
 
     def __init__(self, host, mac, name, pin):
-        """Initialize the sony bravia device."""
+        """Initialize the Sony Bravia device."""
         from braviarc import braviarc
 
         self._pin = pin

homeassistant/components/media_player/cmus.py

@@ -2,9 +2,8 @@
 Support for interacting with and controlling the cmus music player.
 
 For more details about this platform, please refer to the documentation at
-https://home-assistant.io/components/media_player.mpd/
+https://home-assistant.io/components/media_player.cmus/
 """
-
 import logging
 
 from homeassistant.components.media_player import (
@@ -25,7 +24,7 @@ SUPPORT_CMUS = SUPPORT_PAUSE | SUPPORT_VOLUME_SET | SUPPORT_TURN_OFF |  \
 
 
 def setup_platform(hass, config, add_devices, discover_info=None):
-    """Setup the Cmus platform."""
+    """Setup the CMUS platform."""
     from pycmus import exceptions
 
     host = config.get(CONF_HOST, None)
@@ -44,7 +43,7 @@ def setup_platform(hass, config, add_devices, discover_info=None):
 
 
 class CmusDevice(MediaPlayerDevice):
-    """Representation of a running cmus."""
+    """Representation of a running CMUS."""
 
     # pylint: disable=no-member, too-many-public-methods, abstract-method
     def __init__(self, server, password, port, name):

homeassistant/components/media_player/roku.py

@@ -4,7 +4,6 @@ Support for the roku media player.
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/media_player.roku/
 """
-
 import logging
 
 from homeassistant.components.media_player import (

homeassistant/components/media_player/snapcast.py

@@ -4,7 +4,6 @@ Support for interacting with Snapcast clients.
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/media_player.snapcast/
 """
-
 import logging
 import socket
 

homeassistant/components/media_player/universal.py

@@ -4,7 +4,6 @@ Combination of multiple media players into one for a universal controller.
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/media_player.universal/
 """
-
 import logging
 # pylint: disable=import-error
 from copy import copy

homeassistant/components/sensor/openexchangerates.py

@@ -1,4 +1,9 @@
-"""Support for openexchangerates.org exchange rates service."""
+"""
+Support for openexchangerates.org exchange rates service.
+
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/sensor.openexchangerates/
+"""
 from datetime import timedelta
 import logging
 import requests
@@ -41,7 +46,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 
 class OpenexchangeratesSensor(Entity):
-    """Implementing the Openexchangerates sensor."""
+    """Representation of an Openexchangerates sensor."""
 
     def __init__(self, rest, name, quote):
         """Initialize the sensor."""
@@ -87,7 +92,7 @@ class OpenexchangeratesData(object):
 
     @Throttle(MIN_TIME_BETWEEN_UPDATES)
     def update(self):
-        """Get the latest data from openexchangerates."""
+        """Get the latest data from openexchangerates.org."""
         try:
             result = requests.get(self._resource, params={'base': self._base,
                                                           'app_id':

homeassistant/components/sensor/thinkingcleaner.py

@@ -1,4 +1,9 @@
-"""Support for ThinkingCleaner."""
+"""
+Support for ThinkingCleaner.
+
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/sensor.thinkingcleaner/
+"""
 import logging
 from datetime import timedelta
 

homeassistant/components/switch/homematic.py

@@ -1,13 +1,9 @@
 """
-The homematic switch platform.
+Support for Homematic switches.
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/switch.homematic/
-
-Important: For this platform to work the homematic component has to be
-properly configured.
 """
-
 import logging
 from homeassistant.components.switch import SwitchDevice
 from homeassistant.const import STATE_UNKNOWN
@@ -19,7 +15,7 @@ DEPENDENCIES = ['homematic']
 
 
 def setup_platform(hass, config, add_callback_devices, discovery_info=None):
-    """Setup the platform."""
+    """Setup the Homematic switch platform."""
     if discovery_info is None:
         return
 
@@ -29,7 +25,7 @@ def setup_platform(hass, config, add_callback_devices, discovery_info=None):
 
 
 class HMSwitch(homematic.HMDevice, SwitchDevice):
-    """Represents a Homematic Switch in Home Assistant."""
+    """Representation of a Homematic switch."""
 
     @property
     def is_on(self):
@@ -61,24 +57,24 @@ class HMSwitch(homematic.HMDevice, SwitchDevice):
             self._hmdevice.off(self._channel)
 
     def _check_hm_to_ha_object(self):
-        """Check if possible to use the HM Object as this HA type."""
+        """Check if possible to use the Homematic object as this HA type."""
         from pyhomematic.devicetypes.actors import Dimmer, Switch
 
         # Check compatibility from HMDevice
         if not super()._check_hm_to_ha_object():
             return False
 
-        # Check if the homematic device is correct for this HA device
+        # Check if the Homematic device is correct for this HA device
         if isinstance(self._hmdevice, Switch):
             return True
         if isinstance(self._hmdevice, Dimmer):
             return True
 
-        _LOGGER.critical("This %s can't be use as switch!", self._name)
+        _LOGGER.critical("This %s can't be use as switch", self._name)
         return False
 
     def _init_data_struct(self):
-        """Generate a data dict (self._data) from hm metadata."""
+        """Generate a data dict (self._data) from the Homematic metadata."""
         from pyhomematic.devicetypes.actors import Dimmer,\
             Switch, SwitchPowermeter
 

homeassistant/components/switch/thinkingcleaner.py

@@ -1,4 +1,9 @@
-"""Support for ThinkingCleaner."""
+"""
+Support for ThinkingCleaner.
+
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/switch.thinkingcleaner/
+"""
 import time
 import logging
 from datetime import timedelta

homeassistant/components/switch/wake_on_lan.py

@@ -52,7 +52,7 @@ class WOLSwitch(SwitchDevice):
 
     @property
     def is_on(self):
-        """True if switch is on."""
+        """Return true if switch is on."""
         return self._state
 
     @property

homeassistant/components/thermostat/eq3btsmart.py

@@ -1,9 +1,9 @@
 """
 Support for eq3 Bluetooth Smart thermostats.
 
-Uses bluepy_devices library.
+For more details about this platform, please refer to the documentation at
+https://home-assistant.io/components/thermostat.eq3btsmart/
 """
-
 import logging
 
 from homeassistant.components.thermostat import ThermostatDevice

homeassistant/components/thermostat/homematic.py

@@ -1,13 +1,9 @@
 """
-The Homematic thermostat platform.
+Support for Homematic thermostats.
 
 For more details about this platform, please refer to the documentation at
 https://home-assistant.io/components/thermostat.homematic/
-
-Important: For this platform to work the homematic component has to be
-properly configured.
 """
-
 import logging
 import homeassistant.components.homematic as homematic
 from homeassistant.components.thermostat import ThermostatDevice
@@ -20,7 +16,7 @@ _LOGGER = logging.getLogger(__name__)
 
 
 def setup_platform(hass, config, add_callback_devices, discovery_info=None):
-    """Setup the platform."""
+    """Setup the Homematic thermostat platform."""
     if discovery_info is None:
         return
 
@@ -31,7 +27,7 @@ def setup_platform(hass, config, add_callback_devices, discovery_info=None):
 
 # pylint: disable=abstract-method
 class HMThermostat(homematic.HMDevice, ThermostatDevice):
-    """Represents a Homematic Thermostat in Home Assistant."""
+    """Representation of a Homematic thermostat."""
 
     @property
     def unit_of_measurement(self):
@@ -69,7 +65,7 @@ class HMThermostat(homematic.HMDevice, ThermostatDevice):
         return convert(30.5, TEMP_CELSIUS, self.unit_of_measurement)
 
     def _check_hm_to_ha_object(self):
-        """Check if possible to use the HM Object as this HA type."""
+        """Check if possible to use the Homematic object as this HA type."""
         from pyhomematic.devicetypes.thermostats import HMThermostat\
             as pyHMThermostat
 
@@ -77,7 +73,7 @@ class HMThermostat(homematic.HMDevice, ThermostatDevice):
         if not super()._check_hm_to_ha_object():
             return False
 
-        # Check if the homematic device correct for this HA device
+        # Check if the Homematic device correct for this HA device
         if isinstance(self._hmdevice, pyHMThermostat):
             return True
 
@@ -85,7 +81,7 @@ class HMThermostat(homematic.HMDevice, ThermostatDevice):
         return False
 
     def _init_data_struct(self):
-        """Generate a data dict (self._data) from hm metadata."""
+        """Generate a data dict (self._data) from the Homematic metadata."""
         super()._init_data_struct()
 
         # Add state to data dict