Bluetooth: Host: Amend disconnected() callback documentation

The API documentation for the disconnected() callback warns
that the connection object is not actually reusable at this stage,
but some of the advice given may be misleading:
- "start connectable advertising": the options that "will attempt to
  resume the advertiser under some conditions" are deprecated
  (BT_LE_ADV_OPT_CONNECTABLE and related), and the responsibility
  for this behavior has moved to the application [1]
- "increase CONFIG_BT_MAX_CONN": does not really avoid the issue,
  only delays the point where there may be no free connection object
  when the disconnected() callback executes

Also, the documentation predates [2] and [3], and does not mention
the recycled() callback, which is now the most reliable API to track
free connections and/or initiate operations that depend on them.

[1] 8cfad44: Bluetooth: Deprecate adv auto-resume

[2] efb5d83: Bluetooth: Host: Added Recycled evt notifying conn object
                              is available

[3] 2ca59e7: Bluetooth: Host: Defer `conn.recycled()` to the syswq

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

Author: dottspina

include/zephyr/bluetooth/conn.h

@@ -1690,9 +1690,9 @@ 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 is recommended to either use @ref k_work_submit
+	 *  or rely on @ref bt_conn_cb.recycled to create new connections
+	 *  or resume connectable advertising.
 	 *
 	 *  @param conn Connection object.
 	 *  @param reason BT_HCI_ERR_* reason for the disconnection.