move restore mode from gpio/output to base switch (#2381)

components/switch/gpio.rst

@@ -28,17 +28,6 @@ Configuration variables:
   GPIO pin to use for the switch.
 - **name** (**Required**, string): The name for the switch.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-- **restore_mode** (*Optional*): Control how the GPIO Switch attempts to restore state on bootup.
-  For restoring on ESP8266s, also see ``restore_from_flash`` in the
-  :doc:`esp8266 section </components/esp8266>`.
-
-    - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore.
-    - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
-    - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
-    - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
-    - ``ALWAYS_OFF`` - Always initialize the pin as OFF on bootup.
-    - ``ALWAYS_ON`` - Always initialize the pin as ON on bootup.
-
 - **interlock** (*Optional*, list): A list of other GPIO switches in an interlock group. See
   :ref:`switch-gpio-interlocking`.
 - **interlock_wait_time** (*Optional*, :ref:`config-time`): For interlocking mode, set how long

components/switch/index.rst

@@ -31,6 +31,22 @@ Configuration variables:
 - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
   not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
   a ``name`` will implicitly set this to true.
+- **restore_mode** (*Optional*): Control how the switch attempts to restore state on bootup.
+  **NOTE** : Not all components consider **restore_mode**. Check the documentation of the specific component to understand how
+  this feature works for a particular component or device.
+  For restoring on ESP8266s, also see ``restore_from_flash`` in the
+  :doc:`esp8266 section </components/esp8266>`.
+
+    - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore.
+    - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
+    - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
+    - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
+    - ``ALWAYS_OFF`` - Always initialize the switch as OFF on bootup.
+    - ``ALWAYS_ON`` - Always initialize the switch as ON on bootup.
+    - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state. 
+
+  Unless a specific platform defines another default value, the default is ``RESTORE_DEFAULT_OFF``.
+
 - **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform
   when the switch is turned on. See :ref:`switch-on_turn_on_off_trigger`.
 - **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform

components/switch/modbus_controller.rst

@@ -13,6 +13,10 @@ Configuration variables:
 
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - **name** (**Required**, string): The name of the sensor.
+- **restore_mode** (*Optional*): **UNIMPLEMENTED** for this component. See :ref:`Switch <config-switch>`, since this configuration variable is inherited.
+  Restore mode is unimplemented for this component. This means the switch frontend will show an undetermined state until the real state is retrieved from
+  the device on the next refresh. For backward compatibility, once this feature is implemented, the default value for Modbus Controller Switch's **restore_mode** will
+  be ``DISABLED`` (recommended), which leaves initial state up to the hardware: usually the state lives in the device and ESPHome does not need to remember it.
 - **register_type** (**Required**): type of the modbus register.
 - **address** (**Required**, int): start address of the first register in a range
 - **offset** (*Optional*, int): not required in most cases

components/switch/output.rst

@@ -29,16 +29,6 @@ Configuration variables:
 - **output** (**Required**, :ref:`config-id`): The ID of the output component to use.
 - **name** (**Required**, string): The name for the switch.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-- **restore_mode** (*Optional*): Control how the switch attempts to restore state on bootup.
-  For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the
-  :doc:`esphome section </components/esphome>`.
-
-    - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore.
-    - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON.
-    - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF.
-    - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON.
-    - ``ALWAYS_OFF`` - Always initialize the pin as OFF on bootup.
-    - ``ALWAYS_ON`` - Always initialize the pin as ON on bootup.
 
 - All other options from :ref:`Switch <config-switch>`.