[SourceKit] Add documentation for SourceKit request types #3815
Conversation
RLovelett
force-pushed
the
improvement/SR-2117-Add-documentation-for-SourceKit-request-types
branch
from
5b7aad6 to
ef78c90
Compare
- Make the Demangle header match the other headers in the doc (e.g., double hash) - Add a table of contents that is sorted alphabetically by request key with a link to the header in the document
RLovelett
force-pushed
the
improvement/SR-2117-Add-documentation-for-SourceKit-request-types
branch
from
ef78c90 to
54bb408
Compare
|
I added one more commit after I submitted the PR. The new commit adds a "table of contents" to the top of the document that attempts to make it easier to navigate through the document. The table of contents is sorted alphabetically by the key name. Which is different than the order in the document. This may be a cause of concern. Just thought I'd point it out. |
| | [Documentation](#documentation) | source.request.docinfo | | ||
| | [Module interface generation](#module-interface-generation) | source.request.editor.open.interface | | ||
| | [Indexing](#indexing) | source.request.indexsource | | ||
| | [Protocol Version](#protocol-version) | source.request.protocol_version | |
There was a problem hiding this comment.
Wow, this is a huge improvement. Thank you!! 😍
|
I don't mind terribly about the table of contents and the document being in the wrong order for now, but it would be nice to sync them up at some point in the future. Do you think we should alphabetize everything? This has no impact on CI, and I can't imagine anyone would be against more documentation here, so normally I'd merge, but it appears I'm not authorized. I wonder what's up...?
|
|
My guess is that this has something to do with Swift 3 finalization; not sure. Looking into it. |
|
@swift-ci Please smoke test |
|
We need a smoke test because the documentation is built as a part of the build process, and any errors in the markup break the build. |
|
Oh right, I thought that was just for Sphinx and RST files; didn't realize it was for markdown as well. Thanks! |
|
Sorry, I didn't notice this was Markdown. I am not that sure that we build Markdown files, but let's wait until CI finishes. |
RLovelett
deleted the
improvement/SR-2117-Add-documentation-for-SourceKit-request-types
branch
@modocache I agree they really should be in sync. The immediate reason I didn't alphabetize the posts was that I didn't want too big of a change request. I wanted it to be clear that it was purely additive and not step on any toes. To be honest I'm not sure if I think they should be in alphabetical order. When I was playing around with the code I kind of felt that some of the requests were logically grouped together (e.g., the requests with keys that start with Though I could not, and cannot yet, articulate how. So to apply anything other than alphabetical order was beyond me. It seemed like an easy grouping for now until, if?, a high-order grouping appears down the road. |
|
Yeah, that makes sense. If you ever feel like rearranging them, I'd be happy to review that pull request. |
|
I'll work on this again tonight. |
What's in this pull request?
This adds documentation for a few more request types that SourceKit supports. There are no code changes so CI does not need to be run.
Resolvedbug number: (SR-2117)This does not completely resolve SR-2117 but it does knock a few more off the list. It also gives @modocache a chance to say if I am continuing his work appropriately before I spend more hours doing the rest of them.
Before merging this pull request to apple/swift repository:
Triggering Swift CI
The swift-ci is triggered by writing a comment on this PR addressed to the GitHub user @swift-ci. Different tests will run depending on the specific comment that you use. The currently available comments are:
Smoke Testing
A smoke test on macOS does the following:
device standard libraries are not built.
version of these tests are not run.
A smoke test on Linux does the following:
tests are not run.
Validation Testing
Lint Testing
Note: Only members of the Apple organization can trigger swift-ci.