This repository has been archived by the owner on Aug 8, 2023. It is now read-only.
Insert example code in original headers #7569
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1ec5
added
documentation
iOS
|
@1ec5, thanks for your PR! By analyzing this pull request, we identified @boundsj, @incanus and @friedbunny to be potential reviewers. |
|
This is still failing after 3759267: |
|
@1ec5 I pushed the SourceKitten check/install change in 27092f3 that we discussed.
|
friedbunny
reviewed
Jan 3, 2017
|
I’m able to reproduce the test failure only after running the entire test bundle cold – that is, after quitting the simulator. Although we’re careful to initialize the map view with a local style URL, somehow the map ends up loading a Mapbox-hosted source: Here’s the resource being loaded: A little further up the stack, in And further up, in
|
friedbunny
approved these changes
Jan 4, 2017
Use test method names as names of example blocks and test method documentation comments as front matter for examples. Set off example blocks using a syntax similar to playground markup syntax. Avoid hard-coding indentation levels. Trigger Xcode build error when an error occurs in the script.
The comment said 200 while the code said 1,500.
Rewrote the example code insertion script to work on the original source files and overwrite any existing code examples on the same symbols. The script uses SourceKitten to find the documentation comment for the symbol named by the test method. Replaced the Run Script build phase that runs the example code insertion script with a make rule that runs the same script. Inlined skeleton examples minus the contents of the code blocks.
Refactored the example code insertion script to index test methods by their names, then recursively search the SourceKitten output for documentation comments that contain Swift code blocks, replacing each code block with the associated test method body.
The example code insertion script is now platform-agnostic.
Set the map view’s style to a minimal local JSON file. Wait for the style to finish loading before running each test. Corrected CGVector type.
The output of this mode isn’t a good indicator of whether any files would’ve needed to be changed, because the presence of a conditional compilation block in one of the test methods means this script would always change and revert the corresponding comment.
The iOS implementation of MGLMapView tries to show the Streets style by default even if no access token has been set. Avoid a race condition and frequent test failure by specifying the minimal style on initialization.
Keep map views from previous tests from hanging around, potentially obscuring the result of a subsequent test. Set the access token to a bogus token upfront for all style layer tests. Unified MGLStyle usage within MGLStyleTests.
1ec5
force-pushed
the
1ec5-macos-docs-examples
branch
from
3a85e74 to
3e1a24f
Compare
2 tasks
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The script for inserting example code into documentation comments in headers (added in #7337) is no longer run as a build phase. Instead, after you add the Swift code to the test method and add
and any front matter to the original, checked-in headers, you invoke
make darwin-update-examplesmanually. The script inserts the examples into the original checked-in headers instead of the headers in build products. You no longer have to invokemake iframeworkbefore invokingmake idocument.You can invoke the make rule as many times as you like. The headers will always be updated with the latest code from the test methods, even if the code block has already been filled in. This makes
darwin-update-examplesa lot likestyle-code-darwin, except that we still manage the rest of the header (including parts of the comment adjacent to the example) in the header itself. Also, there’s no reminder at the top of every header to invokemake darwin-update-examples. If folks tend to forget to update the examples via the test methods, we could make the script’s dry run output more parsable and run it from within a unit test.The script updates code blocks in all public headers for both the iOS SDK and the macOS SDK. In the event that a header is used by both SDKs and the test method has a conditional compilation block, the iOS version takes precedence over the macOS version. Thanks to type inference in Swift, there’s only one place where conditional compilation is required for passing tests.
In order to reliably associate documentation comments with their symbols, the script calls out to
sourcekitten.Fixes #7565.