Merge pull request #3815 from RLovelett/improvement/SR-2117-Add-documentation-for-SourceKit-request-types

[SourceKit] Add documentation for SourceKit request types

Author: gribozavr

tools/SourceKit/docs/Protocol.md

@@ -16,6 +16,18 @@ The protocol is documented in the following format:
 - `"[opt]"` indicates an optional key.
 - Specific UIDs are written as `<UID string>`.
 
+# Table of Contents
+
+| Request Name | Request Key |
+| -------------:|:------------|
+| [Code Completion](#code-completion) | source.request.codecomplete |
+| [Cursor Info](#cursor-info) | source.request.cursorinfo |
+| [Demangling](#demangling) | source.request.demangle |
+| [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 |
+
 
 # Requests
 
@@ -393,7 +405,7 @@ range ::=
 
 Sub-diagnostics are only diagnostic notes currently.
 
-# Demangling
+## Demangling
 
 SourceKit is capable of "demangling" mangled Swift symbols. In other words,
 it's capable of taking the symbol `_TF13MyCoolPackageg6raichuVS_7Pokemon` as
@@ -455,6 +467,123 @@ Welcome to SourceKit.  Type ':help' for assistance.
 }
 ```
 
+## Protocol Version
+
+SourceKit can provide information about the version of the protocol that is being used.
+
+### Request
+
+```
+{
+	<key.request>: (UID) <source.request.protocol_version>
+}
+```
+
+### Response
+
+```
+{
+	<key.version_major>: (int64) // The major version number in a version string
+	<key.version_minor>: (int64) // The minor version number in a version string
+}
+```
+
+### Testing
+
+```
+$ sourcekitd-test -req=version
+```
+
+or
+
+```
+$ sourcekitd-repl
+Welcome to SourceKit.  Type ':help' for assistance.
+(SourceKit) {
+	key.request: source.request.protocol_version
+}
+```
+
+## Cursor Info
+
+SourceKit is capable of providing information about a specific symbol at a specific cursor, or offset, position in a document.
+
+To gather documentation, SourceKit must be given either the name of a module (key.modulename), the path to a file (key.sourcefile), or some text (key.sourcetext). key.sourcefile is ignored when key.sourcetext is also provided, and both of those keys are ignored if key.modulename is provided.
+
+### Request
+
+```
+{
+	<key.request>:            (UID)     <source.request.cursorinfo>,
+	[opt] <key.sourcetext>:   (string)  // Source contents.
+	[opt] <key.sourcefile>:   (string)  // Absolute path to the file.
+	                                    // **Require**: key.sourcetext or key.sourcefile
+	[opt] <key.offset>:       (int64)   // Byte offset of code point inside the source contents.
+	[opt] <key.usr>:          (string)  // USR string for the entity.
+	                                    // **Require**: key.offset or key.usr
+	[opt] <key.compilerargs>: [string*] // Array of zero or more strings for the compiler arguments,
+                                        // e.g ["-sdk", "/path/to/sdk"]. If key.sourcefile is provided,
+                                        // these must include the path to that file.
+}
+```
+
+### Response
+
+```
+{
+    <key.kind>:                  (UID)    // UID for the declaration or reference kind (function, class, etc.).
+    <key.name>:                  (string) // Displayed name for the token.
+    <key.usr>:                   (string) // USR string for the token.
+    <key.filepath>:              (string) // Path to the file.
+    <key.offset>:                (int64)  // Byte offset of the token inside the souce contents.
+    <key.length>:                (ist64)  // Length of the token.
+    <key.typename>:              (string) // Text describing the type of the result.
+    <key.annotated_decl>:        (string) // XML representing how the token was declared.
+    <key.fully_annotated_decl>:  (string) // XML representing the token.
+    [opt] <key.doc.full_as_xml>: (string) // XML representing the token and its documentation.
+    <key.typeusr>:               (string) // USR string for the type.
+}
+```
+
+### Testing
+
+```
+$ sourcekitd-test -req=cursor -offset=<offset> <file> [-- <compiler args>]
+$ sourcekitd-test -req=cursor -pos=<line>:<column> <file> [-- <compiler args>]
+```
+
+For example, using a document containing:
+
+```
+struct Foo {
+    let bar: String
+}
+```
+
+To get the information about the type `Foo` you would make one of the following requests:
+
+```
+$ sourcekitd-test -req=cursor -offset=7 /path/to/file.swift -- /path/to/file.swift
+$ sourcekitd-test -req=cursor -pos=1:8 /path/to/file.swift -- /path/to/file.swift
+```
+
+Note that when using `sourcekitd-test`, the output is output in an ad hoc text format, not JSON.
+
+You could also issue the following request in the `sourcekitd-repl`, which produces JSON:
+
+```
+$ sourcekitd-repl
+Welcome to SourceKit.  Type ':help' for assistance.
+(SourceKit) {
+  key.request: source.request.cursorinfo,
+  key.sourcefile: "/path/to/file.swift",
+  key.offset: 7,
+  key.compilerargs: [ "/path/to/file.swift" ]
+}
+```
+
+
+
 # UIDs
 
 ## Keys
@@ -472,3 +601,9 @@ Welcome to SourceKit.  Type ':help' for assistance.
 - `key.sourcetext`
 - `key.typename`
 - `key.usr`
+- `key.version_major`
+- `key.version_minor`
+- `key.annotated_decl`
+- `key.fully_annotated_decl`
+- `key.doc.full_as_xml`
+- `key.typeusr`