AntonMeier
commented
4 years ago Excellent feedback. I'll try to update the documentation some time next week. Thanks 👍
Closed marcoburato closed 8 months ago
AntonMeier
commented
4 years ago Excellent feedback. I'll try to update the documentation some time next week. Thanks 👍
Hello, here's my feedback regarding the documentation for the iOS library.
Overall, it's good. The tutorial helps to hit the floor running and the documentation for the API is also nicely done.
What I noticed though, is that some things are given for granted, which can cause confusion. Specifically, here are my observations:
Scan process
This is a minor one. The tutorial says The manager has an integrated scan wizard that takes care of Flic discovery and pairing. Since a wizard is usually a piece of UI that guides the user through a process (ie. install drivers, configure printer, convert between data formats, etc), I thought that would display the same UI the Flic app uses to bind to a button. The following text then says the callback is used to update the UI, which then got me confused. I reckon it would be clearer if the word wizard was not used and there was a sentence like "This method performs the pairing, but it's your job to display a UI while that happens". Also, it should be mentioned that the user is supposed to hold the button down until it pairs. I guessed it would work like in the Flic app, but it'd be better to remove the guesswork.
State and connections
This is where I'm still unsure. The documentation doesn't explain when the buttons connect, if they stay connected, if they will reconnect automatically after the iPhone is rebooted or connection drops due to moving away (or is the iPhone initiating the connection?), etc. I'm sure the "state" restoration in the manager has something to do with this, but we don't know what's in this "state" exactly. Related to this is the usage of the connect/disconnect methods. Are we supposed to disconnect from the buttons to save battery? Will they reconnect back?
Queuing
I haven't looked into this yet, but I'm happy it's supported because I'm interested in the point in time the button was pressed, even if the event can't be delivered immediately to the iPhone. Some more info would be great: is there a maximum time events will stay in the queue? Will the button/phone attempt to reconnect automatically to deliver the events or does it happen at the next push of the button?