[mickdj]

Clarification: We don't use any private API's on iOS, James' comments were with respect to what we do with location and networking.

Apple's documentation is great for most visual elements, but CLLocation* in particular has quite flawed documentation.

[pkaler]

Where are the flaws in CoreLocation or the documentation? CLLocationManager is instantiated like any other NSObject. CLLocationManagerDelegate returns asynchronous results like any other protocol in Cocoa/CocoaTouch. CLLocation, CLHeading, CLRegion are about as close as you're going to get to get to C-style POD structs in Objective-C.

The documentation is all here and the API is about straight forward as it is going to get. http://developer.apple.com/library/ios/#documentation/CoreLo...

[mickdj]

I don't want to veer O/T, but that's not the hard stuff in CLLocation.

There's a lot that could be discussed, but as one example: optimizing for battery conservation requires knowing which radios are currently powered up.

iOS makes its own decision as to which of the 3 styles of location service to engage, based on the desiredAccuracy and distanceFilter values.

However the WiFi/GPS radio have different costs for runtime and warmup, so this API doesn't help when you are attempting to optimize for all 3 of: Accuracy, Timeliness, Battery conservation

Furthermore, the accessible battery percentage in UIDevice.batteryLevel is only reported to the nearest 5%, which is not granular enough to be of use in real-time server-based tweaking.

[pkaler]

There's a lot that could be discussed...

There isn't a whole lot to be discussed. iOS minimizes battery usage based on how close cell towers are, type of cell tower, altitude, Wifi spots database, state of GPS almanac, hardware/driver combination, etc like a any good OS/kernel (including Android) should.

The App sets CLLocationAccuracy to kCLLocationAccuracyBest, kCLLocationAccuracyNearestTenMeters, kCLLocationAccuracyHundredMeters, kCLLocationAccuracyKilometer, or kCLLocationAccuracyThreeKilometers and that's it.

The OS will almost always be able to minimize battery usage because it has way more information than the App could or should ever have. The App will never be able to optimize this setting because there will always be new hardware with new tradeoffs.

Your claim is that Apple's documentation does not describe the implications of the laws of physics for an arbitrary location that the user may reside at and does not reveal implementation details of the kernel that change every hardware/software revision.

The API could not be much simpler or much better documented.

Do you really think that Android's documentation is better? http://developer.android.com/guide/topics/location/obtaining... http://developer.android.com/reference/android/location/pack...

Because the Criteria class on Android is essentially the same as CLLocationAccuracy. http://developer.android.com/reference/android/location/Crit...

I really would like to know if you think that Apple's documentation is poor or if you are just trolling because the facts of the situation don't support your argument.

Which part of the documentation is "quite flawed" like you originally claim?

[jamesg]

So, I will say that I bundled documentation and "openness" into one box, which I probably shouldn't have. The connection is that absented of the "openness" we were really looking for, we sought documentation to describe what's going on. That said...

CoreLocation is a good abstraction. However, its primitives for specifying what trade-offs you are willing to make in acquiring a location are, well, primitive.

A couple of random examples:

- CoreLocation doesn't tell you the source of the location sample (GPS, WiFi, etc). It gives you an estimate of accuracy. Of note, it doesn't give you a measure of the accuracy of the accuracy. This is of import as we have seen examples where the data is off by a whole hemisphere -- I'm not kidding! I understand that exposing these details is kind of "ugly", but obscuring it is removing signals that we could use to figure out the reliability of the data, and what techniques we might be able to use to "clean" the data. I am willing to concede that CL is a good API for general use, but when you're building consumer products, that doesn't cut it. The guy in New York who was reported as being in Antarctica (again, seriously), doesn't really care that the iPhone doesn't provide us the tools to fix that, he just wants it to work (and he's no longer a user).

- Related to the first point, but separate: the implementation of the algorithm for seeking to the desired accuracy is a black box. This makes it really easy to use for basic stuff, but you really don't have any way of knowing the result, in milliwatts, of passing in a given value to that argument. There are ways to mitigate this (which we've had to explore), and we can experiment to learn what the drain is, approximately, but hiding that information has obstructed our development process. Consider also that CL doesn't allow me to specify how long I am willing to wait to get the location fix at the desired accuracy. It does not let me set a budget in milliwatts for a location fix. I realise that Android doesn't provide those exact abstractions, but the tools it does provide make it easier (by which I mean "possible") for me to build them myself.

I also don't think you've successfully made the argument that the OS will know better than us. It's a generic tool, which makes some assumptions. It will have made compromises that don't necessarily work for us. It will not perform optimally for every use case. Going back to something I said before, it seems to optimise for getting to the desired accuracy quickly. For background location tracking apps like ours, that is not a priority. Power is. Neither CoreLocation's abstraction nor documentation provide for this use-case.

[mickdj]

"The OS will almost always be able to minimize battery usage because it has way more information than the App could or should ever have."

This is only true for standalone apps which don't share location information between people.

The OS doesn't know that one person wants to turn on the GPS on another person's phone.

I'm actually pretty pro-Apple and anti-Android (James, OP is the Android developer and I develop exclusively on Obj-C).

[wankerrific]

I'm not sure I agree with the blog post then. The Android docs certainly do not detail this kind of information either.

In fact, I've found the docs for Android to be of the "broad but shallow" variety. That is they cover everything (thanks to Javadoc) but they don't necessarily provide usage guides on the various APIs.

My opinion on Android development vs. iPhone is:

a. GC is convenient

b. The developer docs on Android are not nearly as good as Apple's

c. XCode (while not perfect) is less buggy than Eclipse for basic development activities. Eclipse just gets in the way most of the time and can't keep up with my typing speed which is really frustrating.

d. I like ObjC's dynamism a lot more than Java. This is a personal preference.

e. Its nice to be able to peer into the OS source on Android as the definitive answer for API questions but I suppose if the docs were better you wouldn't need to do that.

f. The Android APIs are full of pattern inconsistencies with their implementation on the whole compared to UIKit which make them more difficult to learn.

g. UI Layout on Android is abysmal compared to using Interface Builder.

i. Again - this is more of a Java thing, but Android lacks the ability to do conditional compilation. You have to go through build system/scripting gymnastics to get what you would get from a simple #IF statement in C.