RubyMine 2018.3 Help

Documenting Source Code in RubyMine

RubyMine provides convenient features to document and annotate your source code in accordance with the YARD, RDoc, and, partly, JSDoc syntax. Quick Documentation Lookup uses documentation comments to get information about methods, classes, modules, and so on. You can also 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: 10 January 2019

See Also

External Links: