Bluetooth: Host: Amend disconnected() callback documentation

The API documentation for the disconnected() callback warns that
the listener can't assume that the corresponding connection object
has been freed and may me available to the application.

The recommendations given to still start a new connection
or connectable advertiser are outdated or misleading:
- "start connectable advertising": the options that "will attempt
  to resume the advertiser under some conditions" are deprecated
  since Zephyr 4.0 (BT_LE_ADV_OPT_CONNECTABLE and related)
- "using k_work_submit()": assuming everything will be fine
  when the work is actually processed is not reliable
- "increase CONFIG_BT_MAX_CONN": setting BT_MAX_CONN to N+1
  when planning N simultaneous connections is a work-around
  that users may have gotten used to (despite its footprint),
  but there is no longer any reason to advise it

Stop documenting creating new connections or restarting advertising
from the disconnected() callback and instead recommend relying
on recycled() for these use cases.

Signed-off-by: Christophe Dufaza <[email protected]>

Author: dottspina

include/zephyr/bluetooth/conn.h

@@ -1877,9 +1877,8 @@ struct bt_conn_cb {
 	 *  start either a connectable advertiser or create a new connection
 	 *  this might fail because there are no free connection objects
 	 *  available.
-	 *  To avoid this issue it is recommended to either start connectable
-	 *  advertise or create a new connection using @ref k_work_submit or
-	 *  increase @kconfig{CONFIG_BT_MAX_CONN}.
+	 *  To avoid this issue, it's recommended to rely instead on @ref bt_conn_cb.recycled
+	 *  which notifies the application when a connection object has actually been freed.
 	 *
 	 *  @param conn Connection object.
 	 *  @param reason BT_HCI_ERR_* reason for the disconnection.