Documenting code
YARD and RDoc are the most popular documentation generation tools used in multiple libraries for documenting code. RubyMine allows you to view documentation written in a YARD or RDoc syntax using Quick Documentation Lookup. Moreover, RubyMine provides extended capabilities to work with YARD tags:
Сreate missing YARD tags
Check the validity of YARD tags and fix them
Utilize YARD tags for better code insight (for example, determining an object type, viewing parameter information for methods, and so on)
Сreate and fix YARD tags
Here we'll show you how to document a method that takes several parameters. In our case, the method takes two arguments and returns the product of these values.
We'll see on how to annotate this method using YARD tags and fix incorrect tags, if necessary.
Add @param tag
-
Place a caret at the method name and press Alt+Enter.
-
In the invoked popup, select the Add @param tag action.
-
RubyMine will add the corresponding comment above the method and will suggest that you specify the type of each parameter value. Start typing Integer and then press Ctrl+Space to view suggestions. Select Integer, press Enter to confirm your choice and press Enter one more time to specify the type of the second parameter.
Configure syntax format for @param tag
By default, RubyMine generates the parameter name after the parameter type (for example, @param [Integer] val1). To change this behavior and set the parameter name before its type (@param val1 [Integer]), do the following:
-
Open the Settings/Preferences dialog (Ctrl+Alt+S).
-
Open the page and select the Add @param tag inspection in the Ruby group.
-
Specify the desired order using the Tag syntax format option.
Remove incorrect YARD tags
When you edit YARD tags, RubyMine checks whether or not any wrong tags exist. For example, this can be a duplicated tag or tag does not have a corresponding parameter in code. To remove an incorrect YARD tag:
-
Place the caret at the highlighted line containing the desired tag and press Alt+Enter.
-
In the invoked popup, select the Remove tag action.
YARD for code insight
RubyMine utilizes YARD type annotations for various code insight features, for example, determining an object type, using the obtained object type in code completion, viewing parameter information for methods, and so on. Let's see on several examples.
View type info
RubyMine uses YARD tags such as @return, @param, or @yieldparam, to determine object types.
Note that RubyMine suggests completion results corresponding to the specified type.
Return/parameter type mismatch
RubyMine can check whether or not the actual return and parameter types for a method match corresponding types provided using the @return and @param annotations. For example, if the method return type does not match the @return type, the editor will show you a warning.
You can manage these warnings using the YARD return type match and YARD param type match inspections.
Parameter info
RubyMine understands the @overload tag and will suggest to you all the declared overloads when showing parameter information.
@type tag
Apart from standard YARD and RDoc tags, RubyMine can process the @type tag to receive information about the variable type. For example, you can use this tag for local variables (with or without variable names) and block parameters:
-
Local variables
# @type [Integer] customer_id = 1 # @type [String] customer_name customer_name = "Andrew Fuller" -
Block parameters
[1, 2, 3].each do |number| # @type [Integer] number puts "#{number}" end