Expand documentation of "built-in discovery flow"

[pdw-mb]

I've recently built my first integration, and struggled with the section on discoverable integrations that require no authentication.

The specific things that confused me are:

1. Is this referring to discovery via built-in discovery methods like DHCP or Bluetooth, or custom discovery mechanisms, or both?
2. "Support all manifest-based discovery protocols." - I'm not sure what this means. Is this referring to built-in discovery mechanisms?
3. "To get started, run python3 -m script.scaffold config_flow_discovery " - it's not clear whether I should run this instead of, or in addition to python3 -m script.scaffold integration?

It would be helpful to have a brief overview of the code side of the "Discoverable Flow", rather than just a link to the scaffold script. I think this amounts to:

• Don't create your own ConfigFlow subclass
• Call homeassistant.helpers.config_entry_flow.register_discovery_flow() and provide a function to detect if there are any discoverable devices.

One final issue I had is that discovery is often done with a timeout (i.e. find all devices that respond within a set period of time), but the function provided to register_discovery_flow() just needs to return True if there is at least one, and then async_setup_entry gets invoked so you can then discover and setup all devices, which leaves the question of how to avoid two full discovery scans? Should you cache the results of discovery in the register_discovery_flow callback (if so, where)?

I'm happy to have a go at drafting improvements, but I don't yet have all the answers.

[pdw-mb]

I've got someway to answering my own questions by reading the source code.

Is this referring to discovery via built-in discovery methods like DHCP or Bluetooth, or custom discovery mechanisms, or both?

I think it's "both", but I'm not entirely sure what you'd provide as the "has_devices" method if you're using manifest-based discovery. If I understand correctly, "has_devices" only gets called if the user manually adds the integration, so I assume that you'd have this return false, unless there is some other way of finding your devices other than manifest-based discovery.

"Support all manifest-based discovery protocols."

I now understand this to mean the built-in discovery mechanisms.

"To get started, run python3 -m script.scaffold config_flow_discovery " - it's not clear whether I should run this instead of, or in addition to python3 -m script.scaffold integration?

I now think that this is instead of, in which case, it'd be good to mention the existence of other scaffold scripts on this page, so that users don't start off with the wrong script.

I'll start drafting some changes, but any confirmation or other input on the above would be appreciated.