Rename source classes

[1ec5]

This PR eliminates MGLAbstractShapeSource, elevating MGLShapeSource and MGLComputedShapeSource to direct subclasses of MGLSource. MGLRasterSource and MGLVectorSource have been renamed MGLRasterTileSource and MGLVectorTileSource, respectively. The class hierarchy now looks like this:

• MGLSource
  • MGLImageSource
  • MGLComputedShapeSource (takes MGLShapeSourceOption)
  • MGLShapeSource (takes MGLShapeSourceOption)
  • MGLTileSource (takes MGLTileSourceOption)
    • MGLRasterTileSource
      • MGLRasterDEMSource
    • MGLVectorTileSource

This is the bare minimum change required to fix #10853. MGLComputedShapeSource’s name still suggests that it’s a subclass of MGLShapeSource, but it’s a minor issue overall. (A computed shape is different than a shape, or something like that.) Once we add an MGLComputedImageSource for #7471, with MGLComputedSource as an intermediate abstract class, I think this naming scheme will make a bit more sense. MGLComputedShapeSource and MGLShapeSource continue to use a Venn diagram of MGLShapeSourceOptions, but this PR comes with some documentation clarifications that should hopefully head off most of the confusion that would cause.

/cc @fabian-guerra @asheemmamoowala

[jfirebaugh]

If we're going to rename MGLRasterSource and MGLVectorSource, why not follow the suggestion in #10853 (comment). In that hierarchy, there's a clear categorization via the suffixes RasterSource and VectorSource, and modifiers such as Computed and Tiled go before those suffixes.

[fabian-guerra]

I just commented about the blurb in the changelog, feel free to dismiss it. LGTM 👍🏼
This is what I reviewed:

• Public class/methods/properties are renamed accordingly to MGLVectorTileSource and MGLRasterTileSource.
• References to previous class names are removed.
• Updated examples documentation.
• Updated Jazzy documentation.
• Updated spec overrides.
• Xcode project updates.

[fabian-guerra]

Will it be useful add the comment that we removed MGLAbstractShapeSource but all MGLShapeSource or MGLComputedShapeSource subclasses are unaffected?

[1ec5]

MGLAbstractShapeSource is new to this release, so the removal should be mentioned in the upcoming beta’s prerelease notes, but not in the final release notes.

[1ec5]

If we're going to rename MGLRasterSource and MGLVectorSource, why not follow the suggestion in #10853 (comment). In that hierarchy, there's a clear categorization via the suffixes RasterSource and VectorSource, and modifiers such as Computed and Tiled go before those suffixes.

First of all, I appreciate the feedback you gave in that issue. Seeing the options laid out that way helped me get past my excessive focus on class hierarchy.

I did try out your suggestion locally but wound up sticking with MGLComputedShapeSource. In my opinion, the main reason for avoiding “shape” in the name of MGLComputedShapeSource would’ve been to keep that class from looking like a subclass of MGLShapeSource, not necessarily to establish a stronger link with MGLVectorSource. (Conceptually and in terms of use cases, it’s a blend of MGLShapeSource and MGLVectorSource, and the new documentation makes that clear.)

The other consideration, I think, is that the relationships between the classes are clearer when each subclass name adds a prefix rather than an infix. MGLShapeVectorSource wouldn’t sound like something you’d say in a sentence: “add a shape vector source to the style”. This is why we renamed MGLStyleConstantValue to MGLConstantStyleValue in #8090. So as this PR is currently written, each class name indicates:

• Whether it’s declarative (implied) or imperative (“computed”)
• The data format (raster tile vs. Mapbox Vector Tiles vs. MGLShape vs. UIImage)

I considered renaming MGLRasterDEMSource to MGLRasterDEMTileSource, but that seemed too pedantic. I’m also biting my tongue to avoid carrying out the unification of MGLShapeSourceOption and MGLTileSourceOption, as proposed in #10853 (comment). It would give us more flexibility in the future, but at the cost of some code completion handholding now.

The nice thing about these changes, minimal as they are, is that we can revisit them during the v4.x timeframe without breaking backwards compatibility:

• If we introduce MGLComputedImageSource, we can have both it and MGLComputedShapeSource inherit from an intermediate MGLComputedSource without breaking any Objective-C or Swift code.
• If we do decide to rename MGLShapeSource and MGLImageSource, we can add compatibility aliases.
• If we unify MGLShapeSourceOption and MGLTileSourceOption, then we can leave around some typedefs that avoid breaking Objective-C code. Some Swift code will require changes (with fix-its), but typically we don’t consider Swift-only changes to be breaking changes.

[asheemmamoowala]

Overall looks good.

I noticed that the documentation specifically calls out shape and vector tile sources as the applicable types for vector layers and filters. DoesMGLComputedShapeSource need to be included in those references as well? ex: MGLCircleStyleLayer. This can be done separately too.

[asheemmamoowala]

Should this be MGLRasterDemTileSource in case we decide to add a computed RasterDEM source in conjunction with computed raster/image source?

[1ec5]

Do you think that’s at least as likely as a computed image source? If so, I think I’d push for some mbgl::style::Source classes to be consolidated, which would allow us to consolidate these classes at the SDK level.

[asheemmamoowala]

I haven't seen any requests for it. And you make a good point, core sources will probably get refactored if we get that far.

[asheemmamoowala]

Should this include computed shape source, or is it implied with 'shape .. source' ?

[1ec5]

This document is meant as a correspondence from style JSON to the runtime styling API. Since computed shape sources can’t be represented in style JSON, I’ve omitted that type here.

[asheemmamoowala]

The optimization is for both large data sets and dynamic ones.

data sets that change dynamically but or are too large to fit completely in memory

[asheemmamoowala]

👍