How to document Ruby code?

Question

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

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

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 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.

Answer 3

I would suggest getting to know RDoc as is stated. But don't ignore the very popular YARD A Ruby Document tool, as well. A lot of the documentation you will see online for Ruby uses Yard. RVM knows Yard and uses it for generating your documentation on your machine if it is available.

RDoc would still be required, as Yard uses it.

Answer 4

Rails has some API Documentation Guidelines. That's probably a good starting point.

Answer 5

You can also check TomDoc for Ruby - still Version 1.0.0-rc1 as of 19.09.2022.

Answer 6

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 7

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