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?

shop.oreilly.com/product/9780596516178.do has a nice little example in the source code. Look in chapter 2 listing. It's about like the answer here. I've played with rdoc just to show source code. You can make your file extension something like my_code.rb to my_code.rb.txt and then run rdoc on it. > rdoc my_code.rb.txt then it won't matter about classes and modules because rdoc will render html for it anyway. Have fun with it. — Douglas G. Allen
– Douglas G. Allen, Commented Apr 29, 2014 at 9:11

rnevius · Accepted Answer · 2018-10-30 08:49:37Z

219

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)

edited Oct 30, 2018 at 8:49

rnevius

27.2k10 gold badges60 silver badges86 bronze badges

answered Nov 5, 2009 at 16:01

Ken Bloom

59.1k14 gold badges114 silver badges171 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

StackedCrooked Over a year ago

How should I document that the outhandler and errhandler parameters may be nil?

Ken Bloom Over a year ago

YARD's annotations may be more powerful, but until it's included in the standard Ruby distribution instead of RDoc, its annotations are not the standard.

Jordan Stewart Over a year ago

The RDoc link is broken try this: github.com/ruby/rdoc. I'll request to edit the answer if everyone is happy with that link.

rnevius · Accepted Answer · 2018-10-30 08:49:51Z

31

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.

edited Oct 30, 2018 at 8:49

rnevius

27.2k10 gold badges60 silver badges86 bronze badges

answered Nov 5, 2009 at 16:00

Topher Fangio

20.7k15 gold badges64 silver badges94 bronze badges

1 Comment

Topher Fangio Over a year ago

Over the years, I've actually switched to YARD as well.

Franklin Yu · Accepted Answer · 2018-07-22 00:48:25Z

27

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.

edited Jul 22, 2018 at 0:48

Franklin Yu

10.1k7 gold badges50 silver badges60 bronze badges

answered Dec 14, 2012 at 15:32

vgoff

11.4k3 gold badges43 silver badges59 bronze badges

2 Comments

doub1ejack Over a year ago

Having used mostly C++, Java, Scala and PHP, I find the @tag notation very familiar.

Franklin Yu Over a year ago

It has been four years and YARD has evolved greatly. It's a pity that YARD is still not included in Ruby. (By the way YARD homepage accepts HTTPS.)

webwurst · Accepted Answer · 2013-02-06 14:24:17Z

19

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

edited Feb 6, 2013 at 14:24

webwurst

4,9603 gold badges27 silver badges33 bronze badges

answered Nov 5, 2009 at 16:00

Hank Gay

72.4k36 gold badges164 silver badges224 bronze badges

Comments

Cadoiz · Accepted Answer · 2022-09-21 09:06:58Z

9

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

edited Sep 21, 2022 at 9:06

Cadoiz

1,7042 gold badges25 silver badges36 bronze badges

answered Dec 14, 2012 at 14:42

onurozgurozkan

1,7942 gold badges23 silver badges34 bronze badges

4 Comments

Michael Easter Over a year ago

FWIW, this one is specified in the GitHub style guide - github.com/styleguide/ruby

Michael Renner Over a year ago

Thanks, tomdoc seems to be a good source for best current practices when it comes to documenting ruby code. Answers the "how" and "why" that's apparently missing from rdoc documentation.

maasha Over a year ago

TomDoc hasn't been kept up to date. Last commit was May 2012.

Franklin Yu Over a year ago

@maasha By 2017 I believe the best bet besides plain RDoc would be YARD, now that it parses the content and makes some fancy hyperlinks to classes and methods.

OscarRyz · Accepted Answer · 2009-11-05 16:00:21Z

2

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

See the sample section on the link I sent you

answered Nov 5, 2009 at 16:00

OscarRyz

200k119 gold badges399 silver badges577 bronze badges

Comments

jrhicks · Accepted Answer · 2009-11-05 16:03:14Z

2

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

answered Nov 5, 2009 at 16:03

jrhicks

15k9 gold badges45 silver badges57 bronze badges

Collectives™ on Stack Overflow

How to document Ruby code?

7 Answers 7

3 Comments

1 Comment

2 Comments

Comments

4 Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

7 Answers 7

3 Comments

1 Comment

2 Comments

Comments

4 Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related