Adopt lightweight generics

[1ec5]

Added lightweight generics annotations to collection-typed method and protocol signatures to streamline usage of these members in Swift. I forgot to take care of this as part of #1578. Again, there are no stability implications, but two big benefits:

• Compiler warnings in Objective-C when we accidentally add non-annotations as annotations or send invalid types inside events.
• Much less as! casting in Swift code that uses Mapbox GL.

/cc @bleege @incanus @friedbunny

[friedbunny]

Should this be <id <MBXAnnotation *>>?

[incanus]

When #1655 lands, it will actually be <MGLPointAnnotation *>.

[1ec5]

No, MBXAnnotation is a concrete implementation of MGLAnnotation.

[incanus]

Right, but that PR implements MGLPointAnnotation as the SDK-provided concrete implementation of MGLAnnotation; that's my point (heh). It mirrors MapKit. Devs will no longer have to create their own point annotation concrete implementation.

[1ec5]

Heh, sorry @incanus, that was in response to @friedbunny. (I was using GitHub’s mobile version, which doesn’t poll for updates.)

[1ec5]

So Travis informs me that lightweight genetics are still off-limits. Xcode 7+ only. 😞

[friedbunny]

Lightweight generics reading, for future reference:

• http://www.miqu.me/blog/2015/06/09/adopting-objectivec-generics/
• https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/BuildingCocoaApps/InteractingWithObjective-CAPIs.html#//apple_ref/doc/uid/TP40014216-CH4-ID173

[1ec5]

Actually, this isn’t blocked: since we only use collections to hold a small number of types, we can use conditionally-defined macros to indicate the same information. Such macros would fool Interface Builder’s parser, but none of the inspectables are collection-typed anyways.

[1ec5]

0d9f251 wraps lightweight generic usage in a conditionally-compiled macro. It all works beautifully, except that the signatures in appledoc-generated documentation now go from:

@property (nonatomic) NSArray<NSString*> *styleClasses

to:

@property (nonatomic) MGL_COLLECTION ( NSArray , NSString **styleClasses

Ouch. This issue is tracked upstream as tomaz/appledoc#373.

[1ec5]

OK, we’re all set now. I worked around tomaz/appledoc#373 by manually replacing all instances of MGL_COLLECTION() in package.sh.

[incanus]

Doesn't this make for a harder-to-read header file?

[1ec5]

Compared to the native Objective-C syntax, not really, in my opinion: MGL_COLLECTION(NSArray, NSString *) * is a little more verbose than NSArray <NSString *> *, but also less likely to be mistaken for good ol’ protocol syntax. It looks like the IBOutletCollection() syntax. For Swift developers, it’s the difference between:

mapView.styleURL = mapView.bundledStyleURLs[0] as! NSURL
mapView.removeAnnotation(mapView.annotations[0] as! MGLAnnotation)
//                                              ^^^ obviously

and:

mapView.styleURL = mapView.bundledStyleURLs[0]
mapView.removeAnnotation(mapView.annotations[0])

And in both Objective-C and Swift, you get an error when you try to pass the wrong kind of objects into -[MGLMapView addAnnotations:] or forget to make your annotation class conform to MGLAnnotation. All in all, I think it’s a useful tradeoff, and we can go back to the native Objective-C syntax when Xcode 7 becomes our minimum supported IDE.

But given that lightweight generics are only bridged for NS[Mutable]Array, NS[Mutable]Set, and NS[Mutable]Dictionary, we could also do something more compact, like NS_ARRAY_OF(NSString *) *. Would that be more readable?

[1ec5]

Well that confused GitHub. This was 91641ff by the way.