Further tweak documentation about _attr-style shorthand for properties (#1000)

* Further tweak documentation about _attr-style shorthand for properties

* Update entity.md

* Update air-quality.md

* Update entity.md

* Update air-quality.md

* Update air-quality.md

* Update device-tracker.md

* Update device-tracker.md

* Update fan.md

* Update vacuum.md

* Update entity.md

* Update entity.md

* Move the example to a separate PR

docs/core/entity.md

@@ -89,7 +89,9 @@ The following properties are used and controlled by Home Assistant, and should n
 | ------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | enabled | boolean | `True`  | Indicate if entity is enabled in the entity registry. It also returns `True` if the platform doesn't support the entity registry. Disabled entities will not be added to Home Assistant. |
 
-## Entity class or instance attributes
+## Property implementation
+
+### Property function
 
 Writing property methods for each property is just a couple of lines of code,
 for example
@@ -105,6 +107,8 @@ class MySwitch(SwitchEntity):
     ...
 ```
 
+### Entity class or instance attributes
+
 Alternatively, a shorter form is to set Entity class or instance attributes according to either of the
 following patterns:
 
@@ -125,9 +129,14 @@ class MySwitch(SwitchEntity):
     ...
 ```
 
-This does exactly the same as the first example. Properties that can be set
-like this, start with `_attr_` followed by the property name. For example,
-the `device_class` property, has the `_attr_device_class` class attribute.
+This does exactly the same as the first example but relies on a default 
+implementation of the property in the base class. The name of the attribute
+starts with `_attr_` followed by the property name. For example, the default
+`device_class` property returns the `_attr_device_class` class attribute.
+
+Not all entity classes support the `_attr_` attributes for their entity 
+specific properties, please refer to the documentation for the respective 
+entity class for details.
 
 :::tip
 If an integration needs to access its own properties it should access the property (`self.name`), not the class or instance attribute (`self._attr_name`).

docs/core/entity/air-quality.md

@@ -12,6 +12,11 @@ separate sensors for these measurements.
 Integrations that still rely on the Air Quality Entity should be migrated.
 :::
 
+:::caution
+The Air Quality entity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
+:::
+
+
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | particulate_matter_2_5 | float | **Required** | The particulate matter 2.5 (<= 2.5 μm) level.

docs/core/entity/device-tracker.md

@@ -17,6 +17,10 @@ Derive a platform entity from [`homeassistant.components.device_tracker.config_e
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 
+:::caution
+ScannerEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
+:::
+
 | Name          | Type    | Default      | Description                                       |
 | ------------- | ------- | ------------ | ------------------------------------------------- |
 | source_type   | string  | **Required** | The source type, eg `gps` or `router`, of the device. |
@@ -44,6 +48,10 @@ Derive a platform entity from [`homeassistant.components.device_tracker.config_e
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 
+:::caution
+TrackerEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
+:::
+
 | Name              | Type    | Default      | Description                                       |
 | ----------------- | ------- | ------------ | ------------------------------------------------- |
 | source_type       | string  | **Required** | The source type, eg `gps` or `router`, of the device. |

docs/core/entity/fan.md

@@ -11,6 +11,10 @@ A fan entity is a device that controls the different vectors of your fan such as
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 
+:::caution
+FanEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
+:::
+
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | current_direction | str | None | Return the current direction of the fan |

docs/core/entity/vacuum.md

@@ -9,6 +9,10 @@ sidebar_label: Vacuum
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 
+:::caution
+VacuumEntity and StateVacuumEntity do not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
+:::
+
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | name | string | **Required** | Name of the device.