Documentation of Rails controllers using yard

Question

When trying to create the documentation of my rails controller and the used parameters I'm getting stuck because yard seems to expect, that the parameters exists as method parameters.

# Renders a list of items
# @param params [Hash] the search parameters
# @option params [String] 'info' Only return items with this specific info
# @option params [Integer] 'limit' Only return <limit> items
def index
  # ... do something smart here
end

So for this documentation yard will raise a warning and doesn't create the documentation:

[warn]: @param tag has unknown parameter name: params 
in file `app/controllers/items_controller.rb' near line 8

Is there a way to document these kinds of items using yard or will I need to do this manually?

Answer 1

I am not aware of a Rails convention to document action parameters through Yard. Will be more than happy to learn about one if anyone out there knows more.

Yard is very flexible. You can for example define your own tags for the project. Add a tag dedicated to document your controller action parameters.

First include the tag definition in the Yard options file .yardopts. Th file is picked up from the project's root directory:

--type-name-tag controller_action_param:"Controller Action Parameters"

Use the new tag in your controller actions like in the example below:

# Renders a list of items
# @controller_action_param :info [String] Only return items with this specific info
# @controller_action_param :limit [Integer] Only return <limit> items
def index
  # ... do something smart here
end

The convention you now defined is that the parameter name is the key used to access the params data - params[:info] for example.

Define a tag name and heading text that suits you most - this is just an example.