Closed friedbunny closed 9 years ago
We might just consider backing out https://github.com/mapbox/mapbox-ios-sdk/commit/c47e8547fe4b12c00af434b8e36e7e3561a0ea92, which introduced this property in the last release. What is the intention of it in CocoaPods, and how do other projects use it?
Also of note: Mapbox.h
contains our "public" headers, which are classes that we endorse, document, and support, as opposed to all of the headers that came from upstream.
Reverting c47e8547fe4b12c00af434b8e36e7e3561a0ea92 has the same effect as this PR (e.g., including all headers), except that it will be less obvious where the headers are coming from.
These are the headers that will be exposed to the user’s project and from which documentation will be generated. If no public headers are specified then all the headers are considered public.
In theory this sounds fine: exclude headers without public API. But our SDK won't compile without these "private" headers. Frankly, I don't understand CocoaPod's implementation/mindset here.
Most other projects use a similar wildcard to what I'm proposing in this PR. AFNetworking, for example: s.public_header_files = 'AFNetworking/*.h'
These are the headers that will be exposed to the user’s project and from which documentation will be generated.
The problem here is CocoaPods trying to be "helpful" and auto-generate documentation that goes here:
http://cocoadocs.org/docsets/Mapbox-iOS-SDK/1.6.1/
In past, I've lobbied (successfully) to get a directive that links to an external place (like our hosted docs) because CocoaDocs was both putting up docs for classes we didn't want up as well as docking us points for not having all classes documented.
It seems though that CocoaDocs is still generating a page for us, even if it's not linked in the summary. So our use of public_header_files
is working.
I'm worried the wildcard will mess up that page again, and people who get there will get an incomplete / inaccurate picture of the toolset.
The cocoapods-headers-yupyup
branch adds the header.dir
property to the podspec, which is: "The directory where to store the headers files so they don't break includes."
That's all it says. Setting header.dir
fixes our compilation errors, but only once you pod update
after you've just pod install
'd.
My inclination here is to go with the wildcard (or reversion) — the library compiling successfully should be our main goal. That CocoaPods is generating docs for us that are wrong and that we can't correct is regrettable, but the lessor evil in this case.
I'll post on the CocoaPods repo about these issues and see what comes of it.
Sounds good @friedbunny — that seems to be the right call. We do link out properly to our own docs page, so let's just go with that and not spend too many cycles on hiding/removing the CocoaDocs version since we'll deprecate before much longer anyway.
With CocoaPods 0.38 and SDK 0.6.1, we switched to explicitly, selectively listing our public headers in the podspec. This caused problems, because we need every header to successfully compile the project.
Rather than maintain a long list of every header, this PR includes all the headers in
MapView/Map/*.h
.Fixes #631, #636
/cc @incanus