Bluetooth: Host: Doc bt_conn_foreach includes disconnected

A user reported confusion about whether disconnected `bt_conn` are
meant to be found by `bt_conn_foreach`. The confusion likely stems from
the inprecise wording "existing connections".

This commit doucments `bt_conn_foreach` as it is: A low-level API for
iterating trough all `bt_conn` objects, connected or not.

This commit also includes a warning about possibly unintutive behavior
in preemptible threads.

Fixes: zephyrproject-rtos#53996

Signed-off-by: Aleksander Wasaznik <[email protected]>

include/zephyr/bluetooth/conn.h

@@ -216,7 +216,17 @@ struct bt_conn *bt_conn_ref(struct bt_conn *conn);
  */
 void bt_conn_unref(struct bt_conn *conn);
 
-/** @brief Iterate through all existing connections.
+/** @brief Iterate through all bt_conn objects.
+ *
+ * Iterates trough all bt_conn objects that are alive in the Host allocator.
+ *
+ * To find established connections, combine this with @ref bt_conn_get_info.
+ * Check that @ref bt_conn_info.state is @ref BT_CONN_STATE_CONNECTED.
+ *
+ * Thread safety: This API is thread safe, but it does not guarantee a
+ * sequentially-consistent view for objects allocated during the current
+ * invocation of this API. E.g. If preempted while allocations A then B then C
+ * happen then results may include A and C but miss B.
  *
  * @param type  Connection Type
  * @param func  Function to call for each connection.