Bluetooth: Host: Amend disconnected() callback documentation

The API documentation for the disconnected() callback warns
that the corresponding connection object is not actually available
to the application at this point.
Recommendations for avoiding this issue are out of date:
- "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

@@ -1835,9 +1835,12 @@ 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 strongly recommended to rely instead
+	 *  on @ref bt_conn_cb.recycled which notifies the application when
+	 *  a connection object has actually been freed.
+	 *
+	 * This callback runs on the system workqueue thread,
+	 * the usual precautions apply.
 	 *
 	 *  @param conn Connection object.
 	 *  @param reason BT_HCI_ERR_* reason for the disconnection.