YARD support in RubyMine
YARD is a popular Ruby documentation generation tool that is used in multiple libraries for documenting code. RubyMine helps you to work with YARD tags and documentation in various ways, for example, you can view the documentation using Quick Documentation Lookup, create missing YARD tags, and check the validity of a YARD tag. RubyMine can also utilize the YARD annotations for better code insight, it uses them to help suggest more relevant results in code completion and parameter hints for methods.
In this blog post, we’ll remind ourselves about the existing capabilities available in RubyMine for YARD and look at the new ones we’ve added.
View documentation
First of all, RubyMine allows you to display the documentation in a popup for methods, classes, etc. To do this, place the caret on the required object and press Ctrl+Q / F1 (View | Quick Documentation).
You can invoke this popup not only from the editor but from completion results, too.
The Quick Documentation popup includes links to the referenced types. This means you can follow the hyperlinks to view the related documentation.
Add and fix YARD tags
Now let’s look at how RubyMine can help us to add new tags. For example, let’s annotate the parameters of the initialize method in the Song class using @param.
To do this, place the caret on the initialize method, press Alt+Enter and select add @param tag. RubyMine will add the corresponding comment above the method and it will suggest that you specify the type of each parameter value.
As you can see, the IDE completes a parameter type when we start typing String or Integer. Note that with this release we have added completion for the Boolean type, it does not exist in Ruby, but it is used in YARD to represent both the TrueClass and FalseClass types.
When you edit YARD tags, RubyMine checks whether or not any duplicated or wrong tags exist, and suggests that you remove any such tags.
By default, RubyMine generates the parameter name after the parameter type (for example, @param [String] name). To change this behavior and set the parameter name before its type (@param name [String]), go to Settings/Preferences (⌘+, / Ctrl+Alt+S), open the Editor | Inspections page, find the Add @param tag inspection in the Ruby group, and specify the desired order.
YARD for code insight
Return and parameter types
One of the most powerful features is that RubyMine can use YARD type annotations to determine an object type. For example, in the following code, we cannot determine the type of size.
def size @file.size end
If we annotate the size method with the @return tag, RubyMine will know the size type in all the places it is called. To try this, place the caret on the size method call and press Ctrl+Shift+P / ⌃⇧P (View | Type Info).
If the method return type does not match the @return type, the editor will show you a warning.
Moreover, RubyMine will suggest completion results corresponding to the specified method.
Of course, type detection works for method parameters, too. If you pass the parameter of incorrect types (String instead of Symbol and Integer in the animation below), the editor will show a corresponding hint.
RubyMine checks the parameter types even for overridden methods whose signature matches the signature of a parent method.
We have introduced parameter and return type checking in this release. You can control it by using the YARD param type match and YARD return type match inspections (Settings/Preferences, the Editor | Inspections page).
Method Overloads
Starting with this release, RubyMine understands the @overload tag and will suggest to you all the declared overloads when calling the method.
For each method overload call, RubyMine can determine the annotated return type.
Yield parameters
Another useful feature we’ve added in this EAP release is support for the @yieldparam tag. This allows the IDE to infer block parameter types.
Try out the new features and let us know about any issues you come across in the comments section. Please also feel free to submit an issue or feature suggestion to YouTrack. Thank you!
Cheers,
Your RubyMine Team
Subscribe to RubyMine Blog updates
