diff --git a/docs/core/entity.md b/docs/core/entity.md
index 25f8d2af..0706913d 100644
--- a/docs/core/entity.md
+++ b/docs/core/entity.md
@@ -14,6 +14,8 @@ from homeassistant.components.switch import SwitchEntity
 
 
 class MySwitch(SwitchEntity):
+    _attr_has_entity_name = True
+
     def __init__(self):
         self._is_on = False
 
@@ -69,6 +71,7 @@ Properties should always only return information from memory and not do I/O (lik
 | 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. |
+| has_entity_name         | boolean |         | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below.
 | name                    | string  | `None`  | Name of the entity  |
 | should_poll             | boolean | `True`  | Should Home Assistant check with the entity for an updated state. If set to `False`, entity will need to notify Home Assistant of new updates by calling one of the [schedule update methods](integration_fetching_data.md#push-vs-poll). |
 | unique_id               | string  | `None`  | A unique identifier for this entity. Needs to be unique within a platform (ie `light.hue`). Should not be configurable by the user or be changeable. [Learn more.](entity_registry_index.md#unique-id-requirements) |
@@ -96,6 +99,25 @@ 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 naming
+
+### `has_entity_name` True (Mandatory for new integrations)
+
+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`.
+
+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`
+- The entity is a member of a device and `entity.name` is not `None`: `friendly_name = f"{device.name} {entity.name}"`
+- The entity is a member of a device and `entity.name` is `None`: `friendly_name = f"{device.name}"`
+
+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).
+
+### `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.
+
 ## Property implementation
 
 ### Property function