-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Generate iOS API documentation using jazzy #3203
Conversation
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. |
Yeah! Looking forward to playing with this tomorrow. |
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. |
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 ( Will push changes soonish. |
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. |
If you prefer the HTML tags, escaping them as |
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. |
@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. |
5c1d1a7
to
71d61c3
Compare
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. |
Really liking jazzy’s approach to undocumented methods following 081e4e4. |
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. |
71d61c3
to
978588c
Compare
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 @friedbunny @incanus for final review. |
823e512
to
c81e3be
Compare
jazzy 0.5.0 is out with the fix for Unicode issues. |
Just upgraded to jazzy 0.5.0. Things are look really good! Except for the |
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 appledocs quirks. The new syntax jives much better with what Xcode expects in terms of auto-indentation and Quick Help. Fixes #1420.
- Change all smart quotes to dumb quotes to workaround SourceKitten bug. - Port changes from OS X (#3135)
llvm.org is down, causing a number of Travis builds to fail (#1828), but the affected code is running only on Bitrise. Merged. |
Restored a build script statement that was accidentally deleted in #3203.
Replaced
appledoc
usage withjazzy
, 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 toappledoc
’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 ofjazzy
, 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, butjazzy
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