Improve FlowManager.async_finish_flow docstring (#126178)

* Improve FlowManager.async_finish_flow docstring

* Fix typos

homeassistant/auth/__init__.py

@@ -127,7 +127,11 @@ class AuthManagerFlowManager(
         flow: data_entry_flow.FlowHandler[AuthFlowResult, tuple[str, str]],
         result: AuthFlowResult,
     ) -> AuthFlowResult:
-        """Return a user as result of login flow."""
+        """Return a user as result of login flow.
+
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+        """
         flow = cast(LoginFlow, flow)
 
         if result["type"] != data_entry_flow.FlowResultType.CREATE_ENTRY:

homeassistant/components/auth/mfa_setup_flow.py

@@ -57,7 +57,11 @@ class MfaFlowManager(data_entry_flow.FlowManager):
     async def async_finish_flow(
         self, flow: data_entry_flow.FlowHandler, result: data_entry_flow.FlowResult
     ) -> data_entry_flow.FlowResult:
-        """Complete an mfs setup flow."""
+        """Complete an mfa setup flow.
+
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+        """
         _LOGGER.debug("flow_result: %s", result)
         return result
 

homeassistant/components/repairs/issue_handler.py

@@ -82,7 +82,11 @@ class RepairsFlowManager(data_entry_flow.FlowManager):
     async def async_finish_flow(
         self, flow: data_entry_flow.FlowHandler, result: data_entry_flow.FlowResult
     ) -> data_entry_flow.FlowResult:
-        """Complete a fix flow."""
+        """Complete a fix flow.
+
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+        """
         if result.get("type") != data_entry_flow.FlowResultType.ABORT:
             ir.async_delete_issue(self.hass, flow.handler, flow.init_data["issue_id"])
         if "result" not in result:

homeassistant/config_entries.py

@@ -1338,7 +1338,11 @@ class ConfigEntriesFlowManager(data_entry_flow.FlowManager[ConfigFlowResult]):
         flow: data_entry_flow.FlowHandler[ConfigFlowResult],
         result: ConfigFlowResult,
     ) -> ConfigFlowResult:
-        """Finish a config flow and add an entry."""
+        """Finish a config flow and add an entry.
+
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+        """
         flow = cast(ConfigFlow, flow)
 
         # Mark the step as done.
@@ -2660,6 +2664,9 @@ class OptionsFlowManager(data_entry_flow.FlowManager[ConfigFlowResult]):
     ) -> ConfigFlowResult:
         """Finish an options flow and update options for configuration entry.
 
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+
         Flow.handler and entry_id is the same thing to map flow with entry.
         """
         flow = cast(OptionsFlow, flow)

homeassistant/data_entry_flow.py

@@ -226,7 +226,11 @@ class FlowManager(abc.ABC, Generic[_FlowResultT, _HandlerT]):
     async def async_finish_flow(
         self, flow: FlowHandler[_FlowResultT, _HandlerT], result: _FlowResultT
     ) -> _FlowResultT:
-        """Finish a data entry flow."""
+        """Finish a data entry flow.
+
+        This method is called when a flow step returns FlowResultType.ABORT or
+        FlowResultType.CREATE_ENTRY.
+        """
 
     async def async_post_init(
         self, flow: FlowHandler[_FlowResultT, _HandlerT], result: _FlowResultT