[SourceKit] docs for complete.open #5645
Conversation
Aghassi
changed the title
|
@benlangmuir Mind reviewing? |
There was a problem hiding this comment.
Thanks for working on this @Aghassi! I have some suggestions inline.
| @@ -54,6 +54,10 @@ provided. | |||
| } | |||
| ``` | |||
|
|
|||
| | Request Name | Request Key | Description | | |||
| | -------------:|:------------|:------------| | |||
| | `open` | `complete.open` | Given an input file, will determine at each offset what keyword is possible. Default offset is `0` if none is provided. | | |||
There was a problem hiding this comment.
I suggest we move this table up above the codecomplete request description, and add both the original codecomplete request and the newer codecomplete.open, codecomplete.close, and codecomplete.update requests. If you only want to cover codecomplete.open in this PR, that's fine, but we should at least add codecomplete as well.
Please note, the request key is codecomplete.open, not just complete.open. For the description, I suggest something like "Open a code-completion session for the given input file and offset, and return the initial list of completions". The key difference between codecomplete.open and codecomplete is that the former opens a session that can filter completions using codecomplete.update and must be closed with codecomplete.close, whereas the latter just returns all of the results without filtering.
We should also describe what else goes in the request, similar to the description of the codecomplete request, or at least describe the differences between that request and this one (I think the only difference in the request structure is that codecomplete.open can take an options dictionary).
| <key.typename>: (string) // Text describing the type of the result. | ||
| <key.context>: (UID) // Semantic context of the code completion result. | ||
| <key.num_bytes_to_erase>: (int64) // Number of bytes to the left of the cursor that should be erased before inserting this completion result. | ||
| <key.substructure>: (dictionary) // Can contains an array the `nameoffset`, `namelength`, `bodyoffset`, `bodylength`, and `substructure`. Other `substructure` will exist if the code complete represents a function. Each one is a paramater of the function |
There was a problem hiding this comment.
I would say, "Contains an array of dictionaries representing ranges of structural elements in the result description, such as the parameters of a function". You don't need to list the keys here since you have them below.
|
@benlangmuir I have pushed a change reflecting your comments. I would like to work and get these initial formatting changes in first before expanding to the other commands. However, I am happy to work on those in a separate PR once this one is done so the foundation is there in case someone has more time to commit to this than I do. Some of the wording in this request is lacking because I'm not 100% on what needs to be said, so I didn't want to say the wrong thing. |
| [opt] <key.sourcetext>: (string) // Source contents. | ||
| [opt] <key.sourcefile>: (string) // Absolute path to the file. | ||
| <key.offset>: (int64) // Byte offset of code-completion point inside the source contents. | ||
| [opt] <key.options>: (dict) // An options dictionary containing keys. |
| @@ -38,6 +38,11 @@ must be given either the path to a file (`key.sourcefile`), or some text | |||
| (`key.sourcetext`). `key.sourcefile` is ignored when `key.sourcetext` is also | |||
| provided. | |||
|
|
|||
| | Request Name | Request Key | Description | | |||
| | -------------:|:------------|:------------| | |||
| | `codecomplete` | `codecomplete` | Given a file will open a code-completion session which can be filtered upon using `codecomplete.update`. Each session must be closed using `codecomplete.close`.| | |||
There was a problem hiding this comment.
This is a description of codecomplete.open. codecomplete just returns completions and does not filter or create a session. Also, you could remove the word "upon" entirely.
- key.codecomplete.options, not key.options - Moved codecomplete definition to codecomplete.open and vice versa
| @@ -40,8 +40,8 @@ provided. | |||
|
|
|||
| | Request Name | Request Key | Description | | |||
| | -------------:|:------------|:------------| | |||
| | `codecomplete` | `codecomplete` | Given a file will open a code-completion session which can be filtered upon using `codecomplete.update`. Each session must be closed using `codecomplete.close`.| | |||
| | `open` | `codecomplete.open` | Open a code-completion session for the given input file and offset, and return the initial list of completions. | | |||
| | `codecomplete` | `codecomplete` | Open a code-completion session for the given input file and offset, and return the initial list of completions. | | |||
There was a problem hiding this comment.
codecomplete does not open a session. It just returns completions.
There was a problem hiding this comment.
So, to clarify, codecomplete would be defined as "Returns completions given an input file and offeset". Does that mean (for my own understanding) it opens a session internally and closes it?
There was a problem hiding this comment.
Abstractly you could sort of think of it that way, but it doesn't really work that way. The "session" for the requests open/close/update is really a way of storing the results we get back from code-completion in the compiler and manipulating them. Code-complete just returns the results and is done.
|
@swift-ci please smoke test and merge |
|
Thanks for working on this! |
|
@swift-ci smoke Test and merge |
Protocol.mdforcomplete.open. I wasn't sure how to format these "sub" commands so to speak, so I did my best. I expect it is going to need some revisions.Resolves SR-2117.