Bluetooth: Host: Amend recycled() callback documentation

The API documentation for the recycled() callback predates [1],
and still warns users to "treat this callback as an ISR",
although it now runs on the system workqueue thread,
as does disconnected().
"Making Bluetooth API calls" to "re-start connectable advertising or
scanning" should no longer be "strongly discouraged".

On the contrary, we can emphasize that this is the right event
to listen for to initiate operations that will try to re-allocate
a freed connection object.

Mention that BT_MAX_CONN configures the size of the connection pool.

Refs:
- [1] efb5d83: Bluetooth: Host: Defer `conn.recycled()` to the syswq

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

Author: dottspina

include/zephyr/bluetooth/conn.h

@@ -1891,12 +1891,13 @@ struct bt_conn_cb {
 	 * This callback notifies the application that it might be able to
 	 * allocate a connection object. No guarantee, first come, first serve.
 	 *
-	 * Use this to e.g. re-start connectable advertising or scanning.
+	 * The maximum number of simultaneous connections is configured
+	 * by @kconfig{CONFIG_BT_MAX_CONN}.
 	 *
-	 * Treat this callback as an ISR, as it originates from
-	 * @ref bt_conn_unref which is used by the BT stack. Making
-	 * Bluetooth API calls in this context is error-prone and strongly
-	 * discouraged.
+	 * This is the event to listen for to start a new connection or connectable advertiser,
+	 * both when the intention is to start it after the system is completely
+	 * finished with an earlier connection, and when the application wants to start
+	 * a connection for any reason but failed and is waiting for the right time to retry.
 	 */
 	void (*recycled)(void);