How to document Ruby code?

Question

Are there certain code conventions when documenting ruby code? For example I have the following code snippit:

require 'open3'

module ProcessUtils

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # - command: command line string to be executed by the system
  # - outhandler: proc object that takes a pipe object as first and only param (may be nil)
  # - errhandler: proc object that takes a pipe object as first and only param (may be nil)
  def execute_and_handle(command, outhandler, errhandler)
    Open3.popen3(command) do |_, stdout, stderr|
      if (outhandler)
        outhandler.call(stdout)
      end
      if (errhandler)
        errhandler.call(stderr)
      end
    end
  end
end

This guess this is okay, but perhaps there are better/superior documentation practices?

Answer 1

The canonical is RDoc it is very similar to the one you've posted.

See the sample section on the link I sent you

Answer 2

I would highly suggest using RDoc. It is pretty much the standard. It is easy to read the code comments, and it allows you to easily create web-based documentation for your project.

Here is a really good introduction to the syntax.

Answer 3

Rails has some official conventions for API documentation. That's probably a good starting point.

Answer 4

You should target your documentation for the RDoc processor, which can find your documentation and generate HTML from it. You've put your comment in the right place for that, but you should have a look at the RDoc documentation to learn about the kinds of tags that RDoc knows how to format. To that end, I'd reformat your comment as follows:

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # +command+:: command line string to be executed by the system
  # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
  # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)

Answer 5

Here is the documentation for the ruby documentation system (RDOC)