Tips for Using Solargraph
Here are some recommendations for getting the most out of Solargraph. The sample screenshots are taken from Visual Studio Code.
Solargraph integrates with YARD to provide rich documentation for classes, modules, and methods. The following example code demonstrates some of the basic features:
# The Foo class # class Foo # The bar method # # @return [String] def bar end end
The descriptions for the
Foo class and the
bar method will appear in VS Code's quick info window for their respective completion suggestions.
@return tag in the bar method's documentation is especially useful. Solargraph uses it to provide String method suggestions when you chain methods,
There are many other YARD tags that Solargraph can use to improve suggestions, such as
@yieldparam. See the
YARD tag documentation for more information.
Detecting and Documenting Variable Types
Solargraph can automatically detect variables' types from their assignments. Any of the following is detectable:
- Literal values (strings, numbers, arrays, and hashes)
- Objects created with #new, e.g., Hash.new
- Any method call with a documented return type
Types will be automatically detected for all of the following:
var1 = "hello" #=> String var2 = var1.join(',') #=> Array var3 = Foo.new #=> Foo (given the above Foo class) var4 = var3.bar #=> String (given the above Foo class)
Solargraph also adds a special
@type tag for documenting variables. Put it directly above a variable assignment to specify its type. It works with local variables, instance
variables, class variables, and constants. Example:
# @type [String] my_string = a_method_that_returns_a_string
Solargraph can provide completion and other features for gems that have YARD documentation. To document your gems, run `yard gems` from the command line.
The VS Code extension provides shortcuts for generating the documentation from the command palette.
The Solargraph server looks for a
.solargraph.yml at the root of a project for configuration settings. In the VS Code extension,
for example, the .solargraph.yml should be in the root folder.
Create a Default Configuration
Go to the project root and run
$ cd /path/to/project $ solargraph config
The default configuration looks something like this:
--- include: - "**/*.rb" exclude: - spec/**/* - test/**/* - vendor/**/* require:  reporters:  domains:  plugins:  max_files: 5000
A list of directory globs to include in Solargraph's code maps. The default configuration includes all .rb files in the folder.
A list of directory globs to exclude from Solargraph's code maps. The default configuration excludes the spec, test, and vendor folders.
require to add require paths that are not explicitly defined in code.
require: - sinatra/base
Solargraph will act as if a file in the project contained the line
reporters to configure diagnostics. Current valid reporters are
rubocop provides RuboCop linting. If your project has a .rubocop.yml file, Solargraph will use
it to configure the linting rules.
require_not_found reports required paths that could not be resolved to either a project file or
Solargraph will use the designated classes and modules as contexts in which the project's scripts
will run. Example: if one of the domains is
Class<Sinatra::Base>, the Sinatra DSL will be included in suggestions. (Whether
you need to specify the domain inside
Class<> depends on how the library is implemented.)
A list of plugins to enhance suggestions. The experimental
runtime plugin is included
in Solargraph, but disabled by default; you need to add it to the
plugins list to activate it:
plugins: - runtime
Warning: The runtime plugin is highly experimental and prone to bugs.
The maximum number of files to be mapped in the workspace. If the workspace exceeds the maximum,
the language server will still map individual files opened in the client. The limit can be removed
altogether by settings
max_files to 0.