From ee769c7d6082d0a5f29d3ea9d75a49c23c097032 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Thu, 18 Aug 2022 17:16:41 +0200
Subject: [PATCH] Clarify entity naming (#1437)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
---
 docs/core/entity.md | 53 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 6 deletions(-)

diff --git a/docs/core/entity.md b/docs/core/entity.md
index 0706913d..94ecd5f3 100644
--- a/docs/core/entity.md
+++ b/docs/core/entity.md
@@ -8,6 +8,10 @@ For a generic introduction of entities, see [entities architecture](../architect
 ## Basic implementation
 
 Below is an example switch entity that keeps track of its state in memory.
+In addition, the switch in the example represents the main feature of a device,
+meaning the entity has the same name as its device.
+
+Please refer to [Entity naming](#entity-naming) for how to give an entity its own name.
 
 ```python
 from homeassistant.components.switch import SwitchEntity
@@ -18,11 +22,8 @@ class MySwitch(SwitchEntity):
 
     def __init__(self):
         self._is_on = False
-
-    @property
-    def name(self):
-        """Name of the entity."""
-        return "My Switch"
+        self._attr_device_info = ...  # For automatic device registration
+        self._attr_unique_id = ...
 
     @property
     def is_on(self):
@@ -68,6 +69,7 @@ Properties should always only return information from memory and not do I/O (lik
 | attribution             | string  | `None`  | The branding text required by the API provider. |
 | available               | boolean | `True`  | Indicate if Home Assistant is able to read the state and control the underlying device. |
 | device_class            | string  | `None`  | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. |
+| device_info             | dict    | `None`  | [Device registry](/docs/device_registry_index) descriptor for [automatic device registration.](/docs/device_registry_index#automatic-registration-through-an-entity)
 | entity_category         | string  | `None`  | Classification of a non-primary entity. Set to `config` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `diagnostic` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. |
 | entity_picture          | URL     | `None`  | Url of a picture to show for the entity. |
 | extra_state_attributes  | dict    | `None`  | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. |
@@ -105,7 +107,8 @@ The following properties are used and controlled by Home Assistant, and should n
 
 The entity's name property only identifies the data point represented by the entity, and should not include the name of the device or the type of the entity. So for a sensor that represents the power usage of its device, this would be “Power usage”.
 
-The main entity of a device may have its name property return `None`.
+If the entity represents a single main feature of a device the entity should typically have its name property return `None`.
+The "main feature" of a device would for example be the `LightEntity` of a smart light bulb.
 
 The `friendly_name` state attribute is generated by combining then entity name with the device name as follows:
 - The entity is not a member of a device: `friendly_name = entity.name`
@@ -114,6 +117,44 @@ The `friendly_name` state attribute is generated by combining then entity name w
 
 Entity names should start with a capital letter, the rest of the words are lower case (unless it's a proper noun or a capitalized abbreviation of course).
 
+#### Example of a switch entity which is the main feature of a device
+
+*Note: The example is using class attributes to implement properties, for other ways
+to implement properties see [Property implementation.](#property-implementation)*
+*Note: The example is incomplete, the `unique_id` property must be implemented, and the entity
+must be [registered with a device.](/docs/device_registry_index#defining-devices)
+
+
+```python
+from homeassistant.components.switch import SwitchEntity
+
+
+class MySwitch(SwitchEntity):
+    _attr_has_entity_name = True
+    _attr_name = None
+
+```
+
+#### Example of a switch entity which is either not the main feature of a device, or is not part of a device:
+
+*Note: The example is using class attributes to implement properties, for other ways*
+*to implement properties see [Property implementation.](#property-implementation)*
+*Note: If the entity is part of a device, the `unique_id` property must be implemented, and the entity
+must be [registered with a device.](/docs/device_registry_index#defining-devices)
+
+```python
+from homeassistant.components.switch import SwitchEntity
+
+
+class MySwitch(SwitchEntity):
+    _attr_has_entity_name = True
+
+    @property
+    def name(self):
+        """Name of the entity."""
+        return "My Switch"
+```
+
 ### `has_entity_name` not implemented or False (Deprecated)
 
 The entity's name property may be a combination of the device name and the data point represented by the entity.