What is the equivalent of a Python docstring in Ruby?

Question

In Python, you can access an object's docstring by using obj.__doc__. What is the equivalent action in Ruby?

Well, perhaps you should first ask whether Ruby has docstrings at all... — , Feb 15 '11 at 16:57

score 25 · Accepted Answer · edited May 28 '22 at 19:55

25

Ruby does not have a Python __doc__ equivalent. They often use Rdoc Format for documentation, for example:

# For example, a square or circle.
class Shape
  # A horizontal position.
  def x
  end

  # A vertical position.
  def y
  end
end

edited May 28 '22 at 19:55

rattray

5,174
1
33
27

answered Feb 15 '11 at 16:58

Tarantula

19,031
12
54
71

so, just to point out, it means that you cannot just look up some info on a method with `print(len.__doc__)` or `help(len)` out of the box in the interpreter. You need a big external tool to do that. – xealits Nov 02 '22 at 23:44

score 4 · Answer 2 · answered Jul 27 '12 at 10:29

Unfortunatelly Ruby does not have any Python like built-in docstrings.

RDoc looks terrible. RDoc is designed to be processed into HTML format and read in the we browser. It's not plain text. Who likes reading HTML-like source code? YARD is better. There is also TomDoc which use just plain text. But none of them compare to Pythonic docstrings which e.g. allow for simple autocompletion from any python console and do need to use any processing tool.

Olly · Answer 3 · 2012-01-31T12:48:21.170

2

I don't believe ruby supports this.

edited Jan 31 '12 at 12:48

answered Feb 15 '11 at 16:55

Olly

3,409
3
24
28

score 2 · Answer 4 · answered Feb 15 '11 at 17:32

2

It's easier to document in Ruby using Yard, which supports different tags like :NODOC:

To document your code with Yard, just write the comment above your code.

# MyClass.new(...) some comment here
class MyClass
end

# foo("bar")
def foo(bar = nil)
end

then run yard on the current working directory of your project, this will generate the $PWD/doc directory for you with a nice set of documentations.

answered Feb 15 '11 at 17:32

JB Juliano

632
1
9
20

4

Yard is an optional way of doing it, however [Rdoc](http://rubydoc.info/stdlib/rdoc/1.9.2/frames) is the standard since it comes with Ruby. – the Tin Man Feb 15 '11 at 18:20

score 0 · Answer 5 · answered Jun 25 '23 at 12:54

Ruby has named HEREDOCS that support various formatting options such as literal, leading whitespace, and others. Two useful articles I found on this are:

Below are some quick examples:

irb(main):001:0" puts <<~TILDE
irb(main):002:0"   This removes leading whitespace to the left
irb(main):003:0"     but preserves indentation underneath it,
irb(main):004:0"     which is quite helpful for formatting.
irb(main):005:0"
irb(main):006:0> TILDE
This removes leading whitespace to the left
  but preserves indentation underneath it,
  which is quite helpful for formatting.

irb(main):007:0" puts <<-LITERAL
irb(main):008:0"     This will do whatevery you
irb(main):009:0"    tell it to do
irb(main):010:0"         which can be nice if you want
irb(main):011:0"      things to be laid out very, very
irb(main):012:0"        p r e c i s e l y
irb(main):013:0"     ... except the problem is you have
irb(main):014:0"       to put this text all the way to the left
irb(main):015:0"     of your code if you want to avoid leading
irb(main):016:0"     whitespace.
irb(main):017:0> LITERAL
    This will do whatevery you
   tell it to do
        which can be nice if you want
     things to be laid out very, very
       p r e c i s e l y
    ... except the problem is you have
      to put this text all the way to the left
    of your code if you want to avoid leading
    whitespace.

HEREDOCS also support string interpolation.

irb(main):018:0> name = 'Jeff'
=> "Jeff"
irb(main):019:0" puts <<~INTERPOLATION
irb(main):020:0"   My name is #{name}
irb(main):021:0> INTERPOLATION
My name is Jeff

What is the equivalent of a Python docstring in Ruby?

5 Answers5