Repository: home-assistant/core
File: homeassistant/components/template/template_entity.py (Python)

Code before:
                setattr(self, attribute, None)
                if self._availability_template:
                    return

                self._attr_available = False
                return

            state = validator(result) if validator else result
            if on_update:
                on_update(state)
            else:
                setattr(self, attribute, state)

        self.add_template(
            option, attribute, on_update=_update_state, on_cancel=on_cancel
        )

    def setup_template(
        self,
        option: str,
        attribute: str,
        validator: Callable[[Any], Any] | None = None,
        on_update: Callable[[Any], None] | None = None,
        on_cancel: Callable[[], None] | None = None,
    ):
        """Set up a template that manages any property or attribute of the entity."""
        self.add_template(option, attribute, validator, on_update, on_cancel, True)

    def add_template_attribute(
        self,
        attribute: str,
        template: Template,
        validator: Callable[[Any], Any] | None = None,
        on_update: Callable[[Any], None] | None = None,
        none_on_template_error: bool = False,
    ) -> None:
        """Call in the constructor to add a template linked to a attribute.

        Parameters
        ----------
        attribute
            The name of the attribute to link to. This attribute must exist
            unless a custom on_update method is supplied.
        template
            The template to calculate.
        validator
            Validator function to parse the result and ensure it's valid.
        on_update
            Called to store the template result rather than storing it
            the supplied attribute. Passed the result of the validator, or None
            if the template or validator resulted in an error.

Review comment (suggestion):
Please improve the docstrings of `setup_state_template`, `setup_template` and `add_template_attribute` so it's clear when to use which alternative.

The `add_template_attribute` docstring explains the meaning of the parameters, please do that in the other methds too.

Code after:
                if self._availability_template:
                    return

                self._attr_available = False
                return

            state = validator(result) if validator else result
            if on_update:
                on_update(state)
            else:
                setattr(self, attribute, state)

        self.add_template(option, attribute, on_update=_update_state)

    def setup_template(
        self,
        option: str,
        attribute: str,
        validator: Callable[[Any], Any] | None = None,
        on_update: Callable[[Any], None] | None = None,
    ):
        """Set up a template that manages any property or attribute of the entity.

        Parameters
        ----------
        option
            The configuration key provided by ConfigFlow or the yaml option
        attribute
            The name of the attribute to link to. This attribute must exist
            unless a custom on_update method is supplied.
        validator:
            Optional function that validates the rendered result.
        on_update:
            Called to store the template result rather than storing it
            the supplied attribute. Passed the result of the validator.
        """
        self.add_template(option, attribute, validator, on_update, True)

    def add_template_attribute(
        self,
        attribute: str,
        template: Template,
        validator: Callable[[Any], Any] | None = None,
        on_update: Callable[[Any], None] | None = None,
        none_on_template_error: bool = False,
    ) -> None:
        """Call in the constructor to add a template linked to a attribute.

        Parameters
        ----------
        attribute