Clarify magic indentation fixes applied to multi-line text edits in CompletionItem

[kdvolder]

It looks like when I create a completion item which contains newlines, so expands to more than one line of actual text... vscode applies some kind of magic indentation fixes to my edit (rather than taking my edit at face value and replacing my text exactly as given).

This is disturbing really because my 'newText' already contains exactly the needed spaces to get the desired/correct indentation. I'm seeing that in vscode additional spaces are added on top of that which actually messes things up.

E.g my language server sends a completion like this:

  {
       "label":"services",
       "kind":5,
       "sortText":"00014",
       "filterText":"services",
       "textEdit": {
            "range":{
                  "start":{"line":2,"character":4},
                  "end":{"line":2,"character":4}
       },
      "newText":"services:\n      - "
 }

There are precisely 4 spaces between the \n and the -.

However, when the completion is invoked it looks like 8 spaces get added into the document instead.

Really, I'd prefer if 'newText' doesn't get subjected to this kind of magic stuff. But if there is indeed magic stuff happening, then we probably should have clear descriptions in the LS spec to explain exactly what magics to expect.

PS: This is somewhat related to #82 (both issues concern a different kind of undocumented 'magic interpretation' applied to the contents of the TextEdit'snewText field).

[dbaeumer]

@jrieken can you please comment. Is there a way to avoid the formatting (e.g. by using the new range property ?)

[dbaeumer]

Moving to January. Need to first understand what exactly is happening and then need to think about a spec.

[jrieken]

The magic is that VS Code prefixes new lines in snippets and completions with the indentation of the 'reference line', that is the line on which the operation was started. So, if your reference line is indented with 4 spaces each new line in your snippet is prefixed with 4 spaces. This is in line with other editors and makes it easy to create snippets and completions without always checking the indentation properties of the current document.

[kdvolder]

Cool, okay. That clarifies it.

I think it it would be convenient if there was a way to enable/disable this magic, maybe by adding a boolean field 'enableMagicIndent' or something like that to the CompletionItem (or to the list to avoid repeating it for every item). To preserve backwards compatibility this field could be optional and the magic indent could be enabled by default if the field is absent.

[kdvolder]

Cool, okay. That clarifies it.

Actually... just a little more nitpicking. I am wondering... how does cursor position (before edit) play into this?

For example, let's say that cursor is shown as <*> and we have this in the editor prior to applying the edit:

   <*>   foo

I.e. there are 3 spaces in front of the cursor and 3 spaces after the cursor. The reference line is indented by 6 spaces (first-non-whitepace char is the 'f' from foo which is preceded by 6 spaces).

It would seem most logical to me 'magic indent' in this case should be 3 spaces rather than 6 (i.e the text after the cursor is not considered). But the simple phrasing of the magic rule as given by @jrieken, above would imply its actually 6 spaces.