Update docstrings

homeassistant/components/scsgate.py

@@ -1,6 +1,6 @@
 """
 homeassistant.components.scsgate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Provides support for SCSGate components.
 
 For more details about this component, please refer to the documentation at
@@ -11,16 +11,13 @@ from threading import Lock
 from homeassistant.core import EVENT_HOMEASSISTANT_STOP
 
 REQUIREMENTS = ['scsgate==0.1.0']
-
-
 DOMAIN = "scsgate"
-
 SCSGATE = None
 _LOGGER = logging.getLogger(__name__)
 
 
 class SCSGate:
-    """ Class dealing with the SCSGate device via scsgate.Reactor """
+    """ Class dealing with the SCSGate device via scsgate.Reactor. """
 
     def __init__(self, device, logger):
         self._logger = logger
@@ -40,7 +37,7 @@ class SCSGate:
             handle_message=self.handle_message)
 
     def handle_message(self, message):
-        """ Method called whenever a message is seen on the bus """
+        """ Method called whenever a message is seen on the bus. """
         from scsgate.messages import StateMessage, ScenarioTriggeredMessage
 
         self._logger.debug("Received message {}".format(message))
@@ -74,31 +71,30 @@ class SCSGate:
 
     @property
     def devices(self):
-        """ Dictionary with known devices. Key is device ID,
+        """
-        value is the device itself """
+        Dictionary with known devices. Key is device ID, value is the device
+        itself.
+        """
         return self._devices
 
     def add_device(self, device):
-        """ Adds the specified device to the list of the already registered ones.
+        """
+        Adds the specified device to the list of the already registered ones.
 
-        Beware: this is not what you usually want to do, take
+        Beware: this is not what you usually want to do, take a look at
-        a look at `add_devices_to_register`
+        `add_devices_to_register`
         """
         self._devices[device.scs_id] = device
 
     def add_devices_to_register(self, devices):
-        """ List of devices to be registered.
+        """ List of devices to be registered. """
-
-        Arguments:
-        * devices: list of devices to register
-        """
         with self._devices_to_register_lock:
             for device in devices:
                 self._devices_to_register[device.scs_id] = device
         self._activate_next_device()
 
     def _activate_next_device(self):
-        """ Starts the activation of the 1st device inside of self._devices """
+        """ Starts the activation of the first device. """
         from scsgate.tasks import GetStatusTask
 
         with self._devices_to_register_lock:
@@ -110,11 +106,7 @@ class SCSGate:
             self._reactor.append_task(GetStatusTask(target=device.scs_id))
 
     def is_device_registered(self, device_id):
-        """ Checks whether a device is already registered or not
+        """ Checks whether a device is already registered or not. """
-
-        Arguments:
-        device_id: the ID of the device to look for
-        """
         with self._devices_to_register_lock:
             if device_id in self._devices_to_register.keys():
                 return False
@@ -126,15 +118,15 @@ class SCSGate:
         return True
 
     def start(self):
-        """ Start the scsgate.Reactor """
+        """ Start the scsgate.Reactor. """
         self._reactor.start()
 
     def stop(self):
-        """ Stop the scsgate.Reactor """
+        """ Stop the scsgate.Reactor. """
         self._reactor.stop()
 
     def append_task(self, task):
-        """ Registers a new task to be executed """
+        """ Registers a new task to be executed. """
         self._reactor.append_task(task)
 
 
@@ -152,8 +144,10 @@ def setup(hass, config):
         return False
 
     def stop_monitor(event):
-        """ Invoked when home-assistant is exiting. Performs the necessary
+        """
-        cleanups """
+        Invoked when home-assistant is exiting. Performs the necessary
+        cleanups.
+        """
         _LOGGER.info("Stopping SCSGate monitor thread")
         SCSGATE.stop()
 

homeassistant/components/tellduslive.py

@@ -1,33 +1,11 @@
 """
 homeassistant.components.tellduslive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tellduslive Component.
 
-Tellduslive Component
+For more details about this component, please refer to the documentation at
-
+https://home-assistant.io/components/tellduslive/
-This component adds support for the Telldus Live service.
-Telldus Live is the online service used with Tellstick Net devices.
-
-For more details about this platform, please refer to the documentation at
-https://home-assistant.io/components/sensor.tellduslive/
-
-Developer access to the Telldus Live service is neccessary
-API keys can be aquired from https://api.telldus.com/keys/index
-
-Tellstick Net devices can be auto discovered using the method described in:
-https://developer.telldus.com/doxygen/html/TellStickNet.html
-
-It might be possible to communicate with the Tellstick Net device
-directly, bypassing the Tellstick Live service.
-This however is poorly documented and yet not fully supported (?) according to
-http://developer.telldus.se/ticket/114 and
-https://developer.telldus.com/doxygen/html/TellStickNet.html
-
-API requests to certain methods, as described in
-https://api.telldus.com/explore/sensor/info
-are limited to one request every 10 minutes
-
 """
-
 from datetime import timedelta
 import logging
 
@@ -38,7 +16,6 @@ from homeassistant.helpers import validate_config
 from homeassistant.const import (
     EVENT_PLATFORM_DISCOVERED, ATTR_SERVICE, ATTR_DISCOVERED)
 
-
 DOMAIN = "tellduslive"
 DISCOVER_SWITCHES = "tellduslive.switches"
 DISCOVER_SENSORS = "tellduslive.sensors"
@@ -80,7 +57,7 @@ class TelldusLiveData(object):
         self._api = TelldusLive(self._client)
 
     def update(self, hass, config):
-        """ Send discovery event if component not yet discovered """
+        """ Send discovery event if component not yet discovered. """
         self._update_sensors()
         self._update_switches()
         for component_name, found_devices, discovery_type in \
@@ -94,7 +71,7 @@ class TelldusLiveData(object):
                                ATTR_DISCOVERED: {}})
 
     def _request(self, what, **params):
-        """ Sends a request to the tellstick live API """
+        """ Sends a request to the Tellstick Live API. """
 
         from tellive.live import const
 
@@ -115,12 +92,12 @@ class TelldusLiveData(object):
         return response
 
     def check_request(self, what, **params):
-        """ Make request, check result if successful """
+        """ Make request, check result if successful. """
         response = self._request(what, **params)
         return response['status'] == "success"
 
     def validate_session(self):
-        """ Make a dummy request to see if the session is valid """
+        """ Make a dummy request to see if the session is valid. """
         try:
             response = self._request("user/profile")
             return 'email' in response
@@ -129,12 +106,12 @@ class TelldusLiveData(object):
 
     @Throttle(MIN_TIME_BETWEEN_UPDATES)
     def _update_sensors(self):
-        """ Get the latest sensor data from Telldus Live """
+        """ Get the latest sensor data from Telldus Live. """
         _LOGGER.info("Updating sensors from Telldus Live")
         self._sensors = self._request("sensors/list")["sensor"]
 
     def _update_switches(self):
-        """ Get the configured switches from Telldus Live"""
+        """ Get the configured switches from Telldus Live. """
         _LOGGER.info("Updating switches from Telldus Live")
         self._switches = self._request("devices/list")["device"]
         # filter out any group of switches
@@ -142,17 +119,17 @@ class TelldusLiveData(object):
                           if switch["type"] == "device"]
 
     def get_sensors(self):
-        """ Get the configured sensors """
+        """ Get the configured sensors. """
         self._update_sensors()
         return self._sensors
 
     def get_switches(self):
-        """ Get the configured switches """
+        """ Get the configured switches. """
         self._update_switches()
         return self._switches
 
     def get_sensor_value(self, sensor_id, sensor_name):
-        """ Get the latest (possibly cached) sensor value """
+        """ Get the latest (possibly cached) sensor value. """
         self._update_sensors()
         for component in self._sensors:
             if component["id"] == sensor_id:
@@ -163,22 +140,22 @@ class TelldusLiveData(object):
                                 component["lastUpdated"])
 
     def get_switch_state(self, switch_id):
-        """ returns state of switch. """
+        """ Returns the state of an switch. """
         _LOGGER.info("Updating switch state from Telldus Live")
         response = self._request("device/info", id=switch_id)["state"]
         return int(response)
 
     def turn_switch_on(self, switch_id):
-        """ turn switch off """
+        """ Turn switch off. """
         return self.check_request("device/turnOn", id=switch_id)
 
     def turn_switch_off(self, switch_id):
-        """ turn switch on """
+        """ Turn switch on. """
         return self.check_request("device/turnOff", id=switch_id)
 
 
 def setup(hass, config):
-    """ Setup the tellduslive component """
+    """ Setup the Telldus Live component. """
 
     # fixme: aquire app key and provide authentication
     # using username + password