Generate iOS API documentation using jazzy

[1ec5]

Replaced appledoc usage with jazzy, which understands modern Objective-C syntax by virtue of using Clang ASTs. Nevertheless, we have to make lots of changes to our documentation syntax, which was tailored to appledoc’s quirks. The new syntax jives much better with what Xcode expects in terms of auto-indentation and Quick Help. (Some further improvements to Objective-C support are coming in the next version of jazzy, which should make the presentation even better.)

jazzy automatically links each method to the code on GitHub that declares it, just like the GL JS documentation. jazzy also supports Mustache-based templates (example), which should make it easier for us to craft templates that match the mapbox.com branding.

Note that jazzy supports Dash docsets instead of Xcode docsets (realm/jazzy#120). Given the current state of the Xcode Documentation window, I think this is an acceptable change. The documentation can be accessed in Xcode via Quick Help in any case.

Along for the ride, I added documentation on the two MGLMapCamera initializers, which were undocumented. Currently, we rely on the appledoc behavior of skipping undocumented methods to skip deprecated methods. I’m continuing that practice through the --skip-undocumented flag, but jazzy makes sure to let readers know that the library is a mere 89% documented. Eventually, we should start leaving in documentation for deprecated methods and instead indicate deprecated status in the documentation comments themselves via the @deprecated tag.

Fixes #1420.

/cc @incanus @friedbunny

[1ec5]

In #3135, I’ve rewritten the majority of the documentation for the OS X port, aiming to capture a lot of map-related nuances that we’ve previously left undocumented. After this PR lands, I’ll bring that rewrite over to iOS.

[1ec5]

Here’s a representative screenshot:

The documentation refers to the Mapbox iOS SDK as simply “Mapbox”, due to the --module flag. We’ll need to change that to “Mapbox iOS SDK” before merging.

[friedbunny]

Yeah! Looking forward to playing with this tomorrow.

[incanus]

Looking really great @1ec5. I want to give this a hard eye before we land it though, and maybe talk about the docset thing — we had maintained an XML feed for updates in Xcode before and there were some complications.

[friedbunny]

I've been poking at this today and bringing in @1ec5's updated verbiage from the OS X branch — things look good generally, but there are some small bugs (mapbox://styles/<user>/<style> brackets not rendering correctly) and changes that I've been making.

Will push changes soonish.

[friedbunny]

Properties not explicitly declared as nonnull are having _Nonnull jammed in:

[1ec5]

The angle brackets are problematic because they're being parsed as HTML tags. I worked around that on this branch with mapbox://styles/my_user_name/abcd1234.

The _Nonnull is Clang-speak. You see that in Quick Help and code completion too. It's worth an issue in jazzy's repo, but we can also work around that easily with postprocessing.

[1ec5]

If you prefer the HTML tags, escaping them as <> should work too.

[friedbunny]

The @deprecated tag is not parsed.

[friedbunny]

I think mapbox://styles/{user}/{style} is a workable alternative to angle brackets.

[1ec5]

A UTF-8 versus UTF-16 issue in jazzy is causing MGLMapView documentation to be fairly brittle around any Unicode characters that may creep into the header: jpsim/SourceKitten#114.

[1ec5]

@incanus, install_docs.sh still uses appledoc to generate an Xcode docset. It doesn’t look like we’ve ever shipped an Xcode docset with the GL-based iOS SDK, so I’m fine with leaving the script as-is until it finally breaks. Meanwhile, jazzy’s Dash docset support is much more likely to be used, since it’ll go live along with the HTML documentation.

[1ec5]

Once this lands, we’ll be able to share MGLAnnotationImage and MGLAnnotationImageDelegate between iOS and OS X (instead of having two separate implementations), using conditional compilation to switch between UIImage and NSImage.

[1ec5]

Really liking jazzy’s approach to undocumented methods following 081e4e4.

[1ec5]

This is currently blocked on supporting both the include/mbgl/darwin/ and include/mbgl/ios/ folders while maintaining the links to source, now that #3135 has landed. Just a matter of generating an umbrella header that includes all the relevant headers using quotes and full paths.

[1ec5]

This is ready to go. We can restore the Unicode characters once jpsim/SourceKitten#114 makes it into a release of jazzy, and we can return to the default jazzy templates once realm/jazzy#411 is fixed. But both changes, as well as stripping out the _Nonnull keywords, can happen after this PR lands.

@friedbunny @incanus for final review.

[1ec5]

jazzy 0.5.0 is out with the fix for Unicode issues.

[1ec5]

Just upgraded to jazzy 0.5.0. Things are look really good! Except for the _Nonnull thing, all the issues described above are resolved.

[1ec5]

llvm.org is down, causing a number of Travis builds to fail (#1828), but the affected code is running only on Bitrise. Merged.

[friedbunny]