Publicly document guidance cards API (and fix naming convention issues)

[avi-c]

The revised Guidance Card styling API needs documenting. It now uses UIAppearance proxies to support custom styling.

See changes in https://github.com/mapbox/mapbox-navigation-ios/pull/2401 and related tickets.

[1ec5]

Specifically, the following symbols and their members need API documentation comments:

https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardCell.swift#L5-L6 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardContainerView.swift#L31 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardContainerView.swift#L49-L50 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L4-L5 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardCollectionDelegate.swift#L4-L5 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardView.swift#L5-L6 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/JunctionView.swift#L6-L7

and the following symbols should no longer have :nodoc: commands:

https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardContainerView.swift#L6-L9 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardContainerView.swift#L283-L284 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L243-L244 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L265-L266 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L289-L290 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L296-L297 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L316-L317 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/MapboxNavigation/InstructionsCardViewController.swift#L327-L328 https://github.com/mapbox/mapbox-navigation-ios/blob/0fb35932f62387b96bac1f0653cf8766c3f6d3bb/Example/ViewController+GuidanceCards.swift#L5-L6

There’s some additional undocumented code related to guidance cards, but it appears to be unused: #2520.

[1ec5]

#2627 adds documentation for the core set of classes needed to hook up guidance cards in an application. I stopped short of documenting all the classes and protocols named above after discovering that the protocols follow the delegate pattern incorrectly. For example, the first argument to this delegate method is inconsistent as to whether it takes a collection view or view controller:

https://github.com/mapbox/mapbox-navigation-ios/blob/8e981508ca664d47223d63ee35163e5373e7dd1d/MapboxNavigation/InstructionsCardCollectionDelegate.swift#L13

By leaving these auxiliary symbols undocumented, we reserve the ability to fix these issues without breaking backwards compatibility in a minor release. We can document these types once they’re ready.

[1ec5]

#2627 has landed; removing the milestone for the rest of the documentation work.