RubyMine 2019.1 Help

Documenting code

Code insight features available in RubyMine for the Ruby language utilize documentation comments created using YARD, RDoc, and, partly, JSDoc syntax, for example:

  • Documentation tags are used for code completion. For example, you can complete the method hash arguments described with the @option tag.

    Code completion for hash parameters

  • Quick Documentation Lookup uses documentation comments to get information about methods, classes, modules, and so on.

    Quick documentation lookup

  • Navigating (Ctrl+B) is used to go from code to documentation.

In this topic, we'll show you how to create and update documentation comments by utilizing intentions and auto-completion available in the RubyMine editor.

Add documentation

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. Our method is declared as follows:

def multiply(val1, val2) end

First, let’s add a tag that describes parameter values. Place a caret at the method name and press Alt+Enter. In the invoked popup, select the Add @param tag intention 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.

Now go inside a method, type the val1 argument value and type a dot to display the available suggestions:

documentation comments in auto-completion

As you can see, RubyMine uses the specified tag, and suggests methods relevant to Integer values.

To add the @return tag to our method, you can also use the corresponding intention action (Add @return tag), or you can do it manually. Add another comment line after the @params tags and type @:

In the suggestions list, select @return and specify the returned value type as Integer. The method will look as follows:

# @param [Integer] val1 # @param [Integer] val2 # @return [Integer] def multiply(val1, val2) val1*val2 end

Update documentation

RubyMine provides the following capabilities to update documentation according to source code changes:

  • If the method declaration contains parameters that do not have corresponding documentation tags, use the Add @param tag intention action:

  • To remove the documentation tag that does not have a corresponding parameter in code, use the Remove tag intention action:

  • To rename a parameter value both in both source code and documentation, use the Rename refactoring. Place a caret at the required parameter, press Shift+F6 and enter a new name:

Add @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
Last modified: 8 May 2019

See Also

External Links: