Skip to content

Latest commit

 

History

History
148 lines (104 loc) · 5.82 KB

autocompletion.md

File metadata and controls

148 lines (104 loc) · 5.82 KB
Raw
id title sidebar_label
autocompletion
Autocompletion
Autocompletion

Sorbet supports autocompletion via LSP.

Some basic features of autocompletion in Sorbet:

  • Sorbet supports completion for method calls, local, instance, and class variables, Ruby keywords, classes, and constants.

  • Completion items will include documentation for the suggestion, when available. Sorbet assumes that a comment immediately above the definition of things like classes, methods, and constants is the documentation for a given item.

    Different language clients may or may not show this information by default.

  • Completion items are sorted by inheritance. Methods defined lower in the inheritance hierarchy show up higher in the completion results. (This is not a perfect heuristic, but it is how Sorbet works.)

There are some more complicated features worth calling out in their own section.

Troubleshooting

No completion results

Support for autocompletion is minimal in # typed: false files, like most other LSP features.

If the file is # typed: true and there are still no completion results, it might be that Sorbet is busy with an ongoing operation. See Showing the Language Server Status to understand what the server statuses mean, and whether Sorbet is able to respond to completion requests given a certain status.

If Sorbet is "Idle" (or "Typechecking in background...") and there are still no completion results, it might be that Sorbet failed to recover from a syntax error in the file. See Syntax error recovery and completion.

If there is no syntax error, it might be that the code path is unreachable. Sorbet does not show completion results for dead/unreachable code paths.

Wrong completion results

If the completion results are present but look wrong, inspect the kind of completion item. For example, VS Code uses these icons to show the completion item kinds:

Sorbet will only ever return completion items with the kind method, variable, field, class, interface, module, enum, or keyword (and sometimes snippet).

Notably, the "abc" icon (word) means the results came either from VS Code’s editor.wordBasedSuggestions setting or some other generic autocomplete extension. (Or, if not using VS Code, then from some other plugin.) Sorbet never produces word completion items.

In specific circumstances (see Completion for method signatures and Completion for YARD snippets), Sorbet will also produce snippet items. In all other cases, snippet items come from some other snippet provider, not Sorbet.

If the completion results still look wrong, please report a bug.

Syntax error recovery and completion

One of the biggest reasons why Sorbet fails to produce completion results is because it failed to recover from a syntax error in the file.

Sorbet has a custom Ruby syntax parser which attempts to recover from many common syntax errors, but it is not perfect. For example:

def foo(x)
  x.
end

This Ruby program has a syntax error, and yet Sorbet is able to recover from it, understanding that this method contains a call on x which is missing the method name.

To see all the known cases where Sorbet fails to recover from parsing a file with a syntax error, see all issues labeled parser.

The biggest known case where Sorbet fails to recover is with mismatched parentheses, brackets, and quotes.

If you think you've found another example that Sorbet should be able to recover from, please open an issue. The Sorbet Playground allows showing the parse result for a file, which is useful for debugging whether Sorbet parsed or failed to parse a given syntax error: simply pass the ?arg=--print=parse-tree-whitequark flag in the query string.

Completion for method signatures

Sorbet can suggest signatures for methods without signatures. Simply typing sig above a method without a signature will trigger a completion item that expands to a snippet with one parameter in the sig for each parameter in the method definition immediately following the sig.

For more information, see Automatically suggesting method signatures

Completion for YARD snippets

Sorbet can suggest a YARD doc snippet for methods.

It will appear after typing ## above a Ruby method or signature, and pre-populate the snippet with one @param for each parameter the method has. Some reminders about these docs:

  • Sorbet recognizes Markdown syntax in these docs, and VS Code will render the Markdown to rich text when showing the documentation.

    Get creative and show examples of how to use your API!

  • These docs show up on hover and in autocompletion items.

  • Sorbet does not read YARD docs for type annotations.

  • See the YARD docs for a list of available tags.