Documentation needs to be clearer about asynchronous events

[logicalelegance]

I've spent some time playing with the SDK this weekend, and noticed an issue in the examples and the documentation.

In all of the examples and docs, things like this are done with blocks:

[[SparkCloud sharedInstance] loginWithUser:@"ido@particle.io" password:@"userpass" completion:^(NSError *error) {
if (!error)
NSLog(@"Logged in to cloud");
else
NSLog(@"Wrong credentials or no internet connectivity, please try again");
}];

Usually followed by a device enumeration step:

__block SparkDevice *myPhoton;
[[SparkCloud sharedInstance] getDevices:^(NSArray *sparkDevices, NSError *error) {
NSLog(@"%@",sparkDevices.description); // print all devices claimed to user

for (SparkDevice *device in sparkDevices)
{
    if ([device.name isEqualToString:@"myNewPhotonName"])
        myPhoton = device;
}

}];

The problem is these network operations are asynchronous and as soon as the login method is invoked, it can move on to the enumeration before that is completed. Similarly, anything done with myPhoton after the device enumeration may not work if that operation hasn't completed. Sometimes it works if the network is fast enough, sometimes it doesn't. It would be nice if this were clearer in the documentation or if there were an easy way to make this synchronous calls..

Thanks for the great work, this is pretty fun stuff!

[idokleinman]

@logicalelegance
Whole SDK was created following the async programming model. You can put your "next step" code inside the success block in order to create a linear flow of events or use GCD semaphores to wait on async network events completing.
What clarifications would you suggest?