Update fan entity docs (#457)

* Update fan entity docs

- Limit allowed speed values to one of the constants SPEED_OFF, SPEED_LOW, SPEED_MEDIUM, SPEED_HIGH.
- Add methods.
- Clean up.

* Update speed typing in turn on

docs/entity_fan.md

@@ -3,7 +3,7 @@ title: Fan Entity
 sidebar_label: Fan
 ---
 
-A fan entity is a device that controls the different vectors of your fan such as speed, direction and oscillation. Derive enitity platforms from ['homeassistant.components.fan.FanDevice'](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/fan/__init__.py).
+A fan entity is a device that controls the different vectors of your fan such as speed, direction and oscillation. Derive entity platforms from ['homeassistant.components.fan.FanDevice'](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/fan/__init__.py).
 
 ## Properties
 
@@ -12,18 +12,17 @@ A fan entity is a device that controls the different vectors of your fan such as
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | current_direction | str | None | Return the current direction of the fan |
-|is_on| boolean | None |Return true if the entity is on |
-| speed | str | None | Return the current speed | 
-| speed_list | list | None| Get the list of available speeds |
-| state_attributes | dict | None | Return optional state attributes |
-| supported_features | int | None | Flag supported features |
+| is_on | boolean | None |Return true if the entity is on |
+| speed | str | None | Return the current speed. One of the values in speed_list. | 
+| speed_list | list | None| Get the list of available speeds. The allowed values are "off", "low", "medium" and "high". Use the corresponding constants SPEED_OFF, SPEED_LOW, SPEED_MEDIUM, SPEED_HIGH. |
+| supported_features | int | 0 | Flag supported features |
 
 
 ## Supported Features
 
 | Constant | Description |
 |----------|--------------------------------------|
-| 'SUPPORT_DIRECTION' | The fan supports changing the direction of it.
+| 'SUPPORT_DIRECTION' | The fan supports changing the direction.
 | 'SUPPORT_SET_SPEED' | The fan supports setting the speed.
 | 'SUPPORT_OSCILLATE' | The fan supports oscillation.
 
@@ -42,7 +41,7 @@ class FanEntity(ToggleEntity):
     def set_direction(self, direction: str) -> None:
         """Set the direction of the fan."""
 
-    async def async_set_direction(self, direction: str):
+    async def async_set_direction(self, direction: str) -> None:
         """Set the direction of the fan."""
 ```
 
@@ -57,7 +56,7 @@ class FanEntity(ToggleEntity):
     def set_speed(self, speed: str) -> None:
         """Set the speed of the fan."""
 
-    async def async_set_speed(self, speed: str):
+    async def async_set_speed(self, speed: str) -> None:
         """Set the speed of the fan."""
 ```
 
@@ -67,13 +66,41 @@ class FanEntity(ToggleEntity):
 class FanEntity(ToggleEntity):
     # Implement one of these methods.
 
-    def turn_on(self, speed: str = None, **kwargs) -> None:
+    def turn_on(self, speed: Optional[str] = None, **kwargs: Any) -> None:
         """Turn on the fan."""
 
-    async def async_turn_on(self, speed: str = None, **kwargs):
+    async def async_turn_on(self, speed: Optional[str] = None, **kwargs: Any) -> None:
         """Turn on the fan."""
 ```
 
+### Turn off
+
+```python
+class FanEntity(ToggleEntity):
+    # Implement one of these methods.
+
+    def turn_off(self, **kwargs: Any) -> None:
+        """Turn the fan off."""
+
+    async def async_turn_off(self, **kwargs: Any) -> None:
+        """Turn the fan off."""
+```
+
+### Toggle
+
+Optional. If not implemented will default to checking what method to call using the is_on property.
+
+```python
+class FanEntity(ToggleEntity):
+    # Implement one of these methods.
+
+    def toggle(self, **kwargs: Any) -> None:
+        """Toggle the fan."""
+
+    async def async_toggle(self, **kwargs: Any) -> None:
+        """Toggle the fan."""
+```
+
 ### Oscillate
 
 Only implement this method if the flag `SUPPORT_OSCILLATE` is set.
@@ -85,7 +112,7 @@ class FanEntity(ToggleEntity):
     def oscillate(self, oscillating: bool) -> None:
         """Oscillate the fan."""
 
-    def async_oscillate(self, oscillating: bool):
+    async def async_oscillate(self, oscillating: bool) -> None:
         """Oscillate the fan."""
 ```
 
@@ -93,4 +120,3 @@ class FanEntity(ToggleEntity):
 
 
 
-