jazzy table of contents specifies nonexistent symbols

[1ec5]

Running document.sh produces the following warnings due to stale entries in the jazzy table of contents:

WARNING: No documented top-level declarations match name "RouteControllerDelegate" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerNotificationUserInfoKey" specified in categories file
WARNING: No documented top-level declarations match name "StyleKitArrows" specified in categories file
WARNING: No documented top-level declarations match name "StylableButton" specified in categories file
WARNING: No documented top-level declarations match name "StylableLabel" specified in categories file
WARNING: No documented top-level declarations match name "RouteStepFormatter" specified in categories file
WARNING: No documented top-level declarations match name "RouteTableViewController" specified in categories file
WARNING: No documented top-level declarations match name "NavigationPulleyViewController" specified in categories file
WARNING: No documented top-level declarations match name "Button" specified in categories file
WARNING: No documented top-level declarations match name "CellSubtitleLabel" specified in categories file
WARNING: No documented top-level declarations match name "CellTitleLabel" specified in categories file
WARNING: No documented top-level declarations match name "DashedLineView" specified in categories file
WARNING: No documented top-level declarations match name "HighlightedButton" specified in categories file
WARNING: No documented top-level declarations match name "LineView" specified in categories file
WARNING: No documented top-level declarations match name "ProgressBar" specified in categories file
WARNING: No documented top-level declarations match name "SeparatorView" specified in categories file
WARNING: No documented top-level declarations match name "SubtitleLabel" specified in categories file
WARNING: No documented top-level declarations match name "TitleLabel" specified in categories file
WARNING: No documented top-level declarations match name "TurnArrowView" specified in categories file
WARNING: No documented top-level declarations match name "WayNameLabel" specified in categories file
WARNING: No documented top-level declarations match name "MaxSecondsSpentTravelingAwayFromStartOfRoute" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMaxManipulatedCourseAngle" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForHighAlertCycling" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForHighAlertDriving" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForHighAlertWalking" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForMediumAlertCycling" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForMediumAlertDriving" specified in categories file
WARNING: No documented top-level declarations match name "RouteControllerMinimumDistanceForMediumAlertWalking" specified in categories file

We should remove any entries that are no longer present in the SDK and rename any entries that were renamed in PRs such as #2230.

/cc @mapbox/navigation-ios

[Udumft]

I did a clean checkout of repo and ran jazzy which resulted in almost empty documentation:

The only category generated is "Guides" which consists of .md files. Anything else, specified in yaml config did not generate (including such 'famous' titles like NavigationViewController, which obviously persists in the code). Corresponding .html files were not generated on the filesystem too.

No new warnings were generated. Log attached:
jazzy.log

I'm not experienced with jazzy, but my guess would be to check how xcodebuild was triggered, because it seems to run suspiciously fast.

[1ec5]

Make sure to run ./scripts/document.sh from the project’s root directory rather than running jazzy directly. This script specifies a number of configuration options and performs some pre- and postprocessing.

[Udumft]

Yes, I did script run, not a direct call.

After some investigation and experimenting I found that docs indeed were not generated due to build configuration. Seems like source files were not found for Jazzy to parse.
I updated MapboxNavigation-Documentation.podspec's source files search path to mirror original podspecs MapboxNavigation.podspec and MapboxCoreNavigation.podspec:
s.source_files = ["MapboxNavigation/**/*.{h,m,swift}","MapboxCoreNavigation"]
... and it worked!

Not sure why it worked previously and why it broke... Anyway, aside of warnings about some really missing or outdated declarations, I see few complains about 'USR'. I remember @1ec5 mentioned it was a known issue, so maybe you can help me save some time here?

isConnected has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an #if block, please ignore this message.
CarPlaySearchController has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an #if block, please ignore this message.
MBRouteState has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an #if block, please ignore this message.

For now I stick to updating the config with up-to-date classes.

[Udumft]

I see that some of the classes, originally listed in yaml config are explicitly marked as :nodoc:. That's why jazzy produces a warning on such cases. This mainly concerns Styling and UI Components elements. Not sure what to do: removed them from doc completely, or provide some basic description?

[1ec5]

CarPlaySearchController and CarPlaySearchController.isConnected are declared in #if blocks. You can ignore the warning since it’s a false alarm for anything declared in an #if block.

MBRouteState shouldn’t be documented, since it isn’t part of the public API. As of #2230, there should no longer be any public C or Objective-C headers in the project. MBRouteState is declared by MBRouteState.h in MapboxNavigationNative. jazzy is pulling it in because we’ve extended it with a public method; this method should be private:

mapbox-navigation-ios/MapboxCoreNavigation/MBNavigator.swift

Line 18 in 9d78861

public var description: String {

[1ec5]

I see that some of the classes, originally listed in yaml config are explicitly marked as :nodoc:. That's why jazzy produces a warning on such cases. This mainly concerns Styling and UI Components elements. Not sure what to do: removed them from doc completely, or provide some basic description?

Some of these classes are part of the NSAppearance system. NSAppearance requires the classes to be public so it can discover them, but developers unknowingly use them as proxy objects when configuring the appearance of the associated views. We should leave the :nodoc: in place and omit them from the table of contents.