DocStrings allows you to define and access Python-like docstrings in Ruby.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install docstrings
class Dog def bark """Tell the dog to bark.""" puts "Woof!" end def sit """ Makes the dog sit. """ @state = :sitting end end Dog.instance_method(:bark).docstring # => "Tell the dog to bark." Dog.new.method(:sit).docstring # => "Makes the dog sit.
How does it work?
Ruby has this odd syntax which allows you to concatenate two strings by simply having them side by side:
"foo" "bar" # => "foobar"
"""Foo""" simply evaluates to
"Foo", and all this gem does is define a method to retrieve this value by using
Wouldn't this cause a performance hit every time the method is called?
Nope! At least, not in CRuby. Ruby is smart enough to recognise when string literals aren't actually used, and will skip generating bytecode for it. Thanks to @charliesome for pointing this out.
def no_docstring nil end def with_docstring """Foo""" nil end puts RubyVM::InstructionSequence.of(method(:no_docstring)).disasm puts "---" puts RubyVM::InstructionSequence.of(method(:with_docstring)).disasm # Output: # == disasm: <RubyVM::InstructionSequence:no_docstring@/tmp/execpad-ecb5745fbd46/source-ecb5745fbd46> # 0000 trace 8 ( 1) # 0002 putnil # 0003 trace 16 ( 3) # 0005 leave # --- # == disasm: <RubyVM::InstructionSequence:with_docstring@/tmp/execpad-ecb5745fbd46/source-ecb5745fbd46> # 0000 trace 8 ( 5) # 0002 putnil # 0003 trace 16 ( 8) # 0005 leave
- Ruby 1.9.x, 2.x
- JRuby 1.9 mode
- Rubinus 1.9 mode
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
LICENSE.txt. It's MIT.