How to document Ruby code?

Question

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)

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.

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.

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

You can also check TomDoc for Ruby - Version 1.0.0-rc1.

http://tomdoc.org/

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

See the sample section on the link I sent you