NimBLEClientCallbacks::onConnectFail() is not working with failing regular client connection

[Berg0162]

I have been testing a connection problem and was happy to insert the onConnectFail() to see when and why the connection failed. Everywhere in the NimBLE-Arduino code and documentation onConnectFail() is described as: Called when a connection attempt fails.

NimBLEClientCallbacks Class Reference
Callbacks associated with a BLE client. More...

#include <NimBLEClient.h>

Public Member Functions
virtual void onConnect (NimBLEClient *pClient)
Called after client connects.

virtual void onConnectFail (NimBLEClient *pClient, int reason)
Called when a connection attempt fails.

...

I was naively surprised that in my code this callback was never ever activated. So I wondered in what circumstances it is called (?)... and started searching and close reading the code!

Only in the CHANGELOG.md, I found a the only and briefly reference to the cause:

[2.1.0] 2024-12-14
Breaking changes
...
NimBLEClientCallbacks::onConnectFail callback that is called when the connection attempt fail while connecting asynchronously.
...

Please change the Class Reference documentation or even better why not make it available while: regular AND asynchronously client connecting

[h2zero]

Thanks, yes, this should be clarified in the docs. It doesn't make much sense to call this from a synchronous connection call as it would return false if the connection failed and you can call getLastError if needed.