-
Notifications
You must be signed in to change notification settings - Fork 318
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Declarations, parameters missing in jazzy documentation #1795
Comments
Forcing the old build system, as shown in realm/jazzy#1009 (comment), might yield better results than the approach I came up with in #1714 (comment). |
These errors produced by jazzy are definitely caused by
The following errors about missing USRs are more concerning. We get one for each symbol that ends up with missing content in the final docset. It makes sense that outputting declarations and such would require a USR. USR errors
The jazzy output ends with this confirmation that we have a huge problem:
|
jazzy’s “no USR” error message tries to reassure us that there’s no problem if the symbol is declared in an |
Removing all the |
Need to try again with jazzy v0.9.5; realm/jazzy#1037 might be a fix for this issue. |
The issue still reproduces with jazzy v0.9.5 and Xcode 10.1 against both master and the v0.21.0 tag, which at the time ran fine. There are three classes of warnings in jazzy’s output that I think we need to get to the bottom of:
This is caused by jpsim/SourceKitten#574. It might be a bit of a red herring. I’m not sure that the failure to get documentation about the MapboxDirections module would cause so much content to go missing, and I don’t recall seeing this warning before when opening this issue.
These conflicting type declarations are concerning, but as far as I can tell, they predate the issue.
We started seeing a variant of this warning on occasion in #1339, but it turned into a deluge as a symptom of the issue being tracked here. One thing I noticed is that #1339 involves |
The fix in jpsim/SourceKitten#575 makes the MapboxDirections.swift warning go away, but the other warnings remain. For posterity, to take advantage of a fix in SourceKitten master:
|
The USRs aren’t contained in the SourceKit output, either. CocoaPods generates a Pods.xcodeproj containing a MapboxNavigation-Documentation target thanks to MapboxNavigation-Documentation.podspec. Opening the project produces these build system errors:
This is a matter of making the podspec exclude Info.plist from the sources: diff --git a/MapboxNavigation-Documentation.podspec b/MapboxNavigation-Documentation.podspec
index 295768e7..df5d55c1 100644
--- a/MapboxNavigation-Documentation.podspec
+++ b/MapboxNavigation-Documentation.podspec
@@ -32,7 +32,7 @@ Pod::Spec.new do |s|
# ――― Source Code ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
- s.source_files = ["MapboxNavigation/*", "MapboxCoreNavigation/*"]
+ s.source_files = ["MapboxNavigation/**/*.{h,m,swift}", "MapboxCoreNavigation/**/*.{h,m,swift}"]
# ――― Resources ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
Building the target manually inside Xcode produces the following compiler error:
After renaming MapboxCoreNavigation/Constants.swift to CoreConstants.swift, the following compiler error remains:
This of course gets to the fundamental reason we went with the CocoaPods hack in #285. Not sure why this doesn’t crop up when building the navigation SDK normally, but a deployment target of iOS 9 means certain API usage gets flagged:
Fixing all these errors resolves all the warnings about USRs other than:
Fixing that last one required upgrading the codebase to Swift 4.2, but that’s a little tricky, because After stubbing out the iOS 9 version of those methods, the codebase is converted to Swift 4.2, and the warnings about missing USRs are all gone. Also, the jazzy summary looks a lot better than in #1795 (comment):
But the declarations and arguments are still missing. |
That was a major case of PEBKAC; the docset is actually fixed with all these changes. For posterity, this is an example invocation of sourcekitten doc command
|
#1952 fixes this issue, leaving only the following warnings:
|
#1952 fixed this issue in v0.29.0, but it came right back in v0.30.0. 😣 |
The v0.30.0-beta.1 docset is fine. It isn’t more fallout from CocoaPods/CocoaPods#8637 (which has been duped to CocoaPods/CocoaPods#8635), because we already re-pushed a new pod that’s compatible with CocoaPods v1.6.1. I don’t recall seeing any USR warnings when building the v0.30.0 docset, but I’m seeing them all now. |
#2078 tracks adding a CI step so the docset doesn’t regress again. |
The published jazzy documentation only contains abstracts, no declarations or parameter listings. As a result, permalinks to individual methods are also broken, and overloaded methods are difficult to distinguish from each other.
This issue reproduces in the documentation for v0.21.0 and above but not for v0.20.1 and below. In v0.21.0 and above, we had to follow the convoluted steps in #1714 (comment) to publish the docset in the first place, so it’s possible that something along the way is preventing jazzy from matching USRs to the source code. The problem might even be the workaround for realm/jazzy#11 that locally blows away
@availability
attributes, but that might be a red herring./cc @mapbox/navigation-ios @mapbox/docs
The text was updated successfully, but these errors were encountered: