Using Annotations
Basics
To make your code readable, it a good idea to annotate it. RubyMine provides various annotations, based partly on YARD, partly on JSDoc.
When a user invokes quick documentation, RubyMine displays the information taken from annotations.
Extracting types from the YARD annotations
Consider the following method:
# @return [String]
def black_box(param1, param2)
endThe only information about the method is the return type, specified in the YARD tag. This is enough for RubyMine to suggest proper code completion (Ctrl+Space):
If the parameter type is declared in the documentation comment, then code completion inside the method body suggests only the relevant choices:
Intention actions suggest to create YARD tags, if missing
If in the same code block, the @return or @param tags are missing, RubyMine provides intention actions (Alt+Enter):
In-place rename refactoring
The rename refactoring involves the YARD tags:
Code inspections and quick fixes
RubyMine validates the tags for duplicated or wrong parameter names:
Annotating local variables
Local variables can be annotated both with or without the variable names:
# @type [String]
my_var = magic_method
# @type my_var [String]
my_var = magic_method
# @type [String] my_var
my_var = magic_method
# @type [String] my_var Add some documentation here
my_var = magic_methodAlso, RubyMine supports multiple assignments:
# @type my_var [String] The first part
# @type other_var [Array<String>] The second part
my_var, other_var = magic_methodAnnotating block parameters
method_with_block do
# @type [String] param1
# @type [Range] param2
| param1, param2 |
# some code...
endViewing Quick Documentation popup
RubyMine properly renders the annotation tags in the quick documentation pop-up window.
For example, this is how RubyMine renders the YARD tags:
The following image demonstrates how RubyMine shows type annotations:
