swiftlang/swift

[SR-2117] Add documentation for SourceKit request types

Open

#44,725 opened on Jul 19, 2016

View on GitHub
 (3 comments) (0 reactions) (0 assignees)Swift (69,989 stars) (10,719 forks)batch import
good first issueimprovement

Description
Previous ID SR-2117
Radar None
Original Reporter @modocache
Type Improvement
Votes 0
Component/s Source Tooling
Labels Improvement, StarterBug
Assignee None
Priority Medium

md5: c43f5bd8eac7b069dfaac26bb719e804

Issue Description:

The majority of SourceKit request types, and the format of their responses, is undocumented. Protocol.md documents a small portion of the request types.

We should add documentation for the remaining request types:

  2. source.request.crash_exit

  4. source.request.mangle_simple_class PR #4733

  9. source.request.codecomplete.close

  10. source.request.codecomplete.update

  11. source.request.codecomplete.cache.ondisk

  12. source.request.codecomplete.setpopularapi

  13. source.request.codecomplete.setcustom

  15. source.request.relatedidents

  16. source.request.editor.open

  18. source.request.editor.open.interface.header

  19. source.request.editor.open.interface.swiftsource

  20. source.request.editor.open.interface.swifttype

  21. source.request.editor.extract.comment

  22. source.request.editor.close

  23. source.request.editor.replacetext

  24. source.request.editor.formattext

  25. source.request.editor.expand_placeholder

  26. source.request.editor.find_usr

  27. source.request.editor.find_interface_doc

  28. source.request.buildsettings.register

  29. source.request.module.groups

To contribute:

  1. Build the Swift compiler from source on macOS. You should have a copy of sourcekitd-test and sourcekitd-repl in your swift-macosx-x86_64/bin build directory.

  2. Try invoking sourcekitd-test -req=foo, where foo is one of the values in this list: https://github.com/apple/swift/blob/7ac11087de44eb17855e6306d22bb9f345140a1d/tools/SourceKit/tools/sourcekitd-test/TestOptions.cpp#L136-L140. You'll need to read the source code to figure out what parameters the request types need to be passed.

  3. Look at the response, and document its structure in https://github.com/apple/swift/blob/master/tools/SourceKit/docs/Protocol.md

Contributor guide

Tech stack
swift
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Build Swift from source on macOSBasic understanding of SourceKitRead C++ source code in TestOptions.cpp
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Start by reading the issue description to understand the request types that still need documentation. Build Swift from source as described, then use `sourcekitd test` to explore the undocumented request types. Read the source code in `tools/SourceKit/tools/sourcekitd test/TestOptions.cpp` to determine parameters. Document the request types and their response format in `tools/SourceKit/docs/Protocol.md`. Refer to existing PRs for examples of similar documentation.