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?
Best Answer
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: