Burlington Ruby: Contributing to Ruby

Burlington Ruby: Contributing to Ruby

Newcomer or seasoned veteran looking to get involved with Ruby documentation? We’ll show you it’s not as scary as it may seem, and there’s plenty of ways to help. It’s important to give back to the open source community and improve things for future developers.

This talk will teach you the value of open-source, the benefits of contributing, and a little bit about how ruby-core works. You will learn what to look for when spotting documentation bugs in the MRI source code. We will cover the guidelines to writing MRI documentation, and how to submit a patch. Including helpful tricks using ri and rdoc.


Zachary Scott

January 30, 2013


  1. 4.
  2. 5.
  3. 7.

    “Ask not what your code can do for you –

    ask what you can do for your code” – John F. Kennedy
  4. 8.
  5. 18.

    Cynicism An attitude characterized by a general distrust of others'

    apparent motives or ambitions, or a general lack of faith or hope in individuals with desires, hopes, opinions, that a cynic perceives as unrealistic or inappropriate, therefore deserving of ridicule or admonishment.
  6. 21.

    Open source lets you read code and get feedback from

    some of the most gifted and experienced engineers in the industry.
  7. 29.

    MRI is only about 70% covered by documentation. Existing docs

    can be improved. Writing docs is a gentle introduction to open source.
  8. 32.
  9. 36.

    Assign doc reports or patches to me and use “DOC”

    category Bugs and features go to maintainer https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers Documentation counts as a bug
  10. 43.

    We provide a fork of ruby on github Like docrails,

    without public write Low noise to signal ratio, very welcoming community.
  11. 44.

    Any questions can be directed to the mailing list or

    IRC documenting.ruby@librelist.org and #ruby-core on freenode.net
  12. 46.

    Try out new features Review open tickets Reproduce bug reports

    against trunk Write tests for new features https://bugs.ruby-lang.org/projects/ruby/wiki/HowToReport
  13. 47.

    Most importantly... Test your app or library against trunk and

    latest preview releases. Many libraries can benefit from this.
  14. 49.

    A github account and git installed http://github.com/ https://help.github.com/articles/set-up-git Subscribe to

    documenting.ruby@librelist.org http://librelist.com/help.html System ruby installed http://www.ruby-lang.org/en/downloads/
  15. 50.

    Latest version of rdoc $ gem install rdoc –pre A

    fork of documenting-ruby https://github.com/documenting-ruby/ruby https://help.github.com/articles/fork-a-repo A copy of the MRI source $ git clone git://github.com/documenting-ruby/ruby.git
  16. 51.

    Text editor of your choice “ .vimrc config for ruby-core

    indent C coding style au FileType c setl ts=8 sw=4 softtabstop=4 noexpandtab set autoindent
  17. 53.

    “What's in a patch? That which we call a patch

    By any other name would merge as clean.” – William Shakespeare
  18. 54.

    Use the latest code One kind of modification per patch

  19. 56.

    Writing new documentation Undocumented areas and examples of good documentation

    http://documenting-ruby.org/undocumented-areas.html Documenting new features Requires some research
  20. 58.

    Writing documentation for our imaginary ruby library. ## # Here

    we would put our class overview class Foo ## # Here we document a class method ::new def initialize(bar) # … do something with bar End end
  21. 61.

    === Headers * simple * lists [labeled] lists or definition

    lists [need] the label in square brackets you:: can also use two colons instead:: of brackets
  22. 62.

    When you have individual words, you can wrap the word

    in the following: *'s for bold, _'s for emphasis or +'s for code
  23. 63.

    If you have more than one word, you need to

    use the following: <b>'s for bold, <em>'s for emphasis, or <tt>'s for code
  24. 66.

    All top-level classes and modules should have an overview. Explain

    why you would want to use this library. Include small examples showing the major features of the library.
  25. 67.

    Internal classes should contain an overview of the library of

    its specific use in the library. An example of this is IRB::XMP, which is an example printer that comes with irb.
  26. 68.

    For implementation specific classes, providing documentation for future maintainers is

    acceptable. The :nodoc: directive can be used to hide this class from the generated developer documentation.
  27. 69.

    RDoc will ignore private and protected methods when generating HTML

    documentation, however ri will include these. Be sure to document all methods, or mark them as :nodoc:
  28. 70.

    For method arguments use the :arg: or :args: directives. Block

    parameters can be documented with the :yields: directive.
  29. 71.

    :call-seq: is used throughout MRI documentation as the goto way

    to provide method description. ## # :call-seq: # some_method(string, separator, limit) → string some_method(str, sep, l)
  30. 72.

    Using :call-seq: is a great way to provide more obvious

    parameter names. The new parameter names can be used within the documentation of the method and should be surrounded by +'s to allow rdoc to find undocumented method parameters.
  31. 73.

    Avoid placing class names and method names in any markup,

    like +, <code> or <tt>. This allows rdoc to create cross-references between various pages of documentation.
  32. 74.

    You can link to class methods within the same scope

    using the double-colon (::) prefix. ## # See also ::new
  33. 75.

    In order to link to instance methods, you must use

    the # prefix. ## # Same as #gsub except substitution # occurs in place.
  34. 76.

    When documenting C files, look for the :Document-class: directive. Also,

    rb_define_class and rb_define_method which are usually at the bottom will reference the C functions you should document.
  35. 77.

    RDoc comes with a handful of directives for documenting C

    level classes, modules, methods, etc http://rdoc.rubyforge.org/RDoc/Parser/C.html
  36. 83.

    Add the files you changed, commit and then push the

    changes to your fork: $ git add . $ git commit -m “add documentation for WHAT_YOU_CHANGED” $ git push
  37. 87.

    Hide an entire block from RDoc by using the :stopdoc:

    and :startdoc: directives. You can also use the “--” and “++” directives. ## # :startdoc: # This is parsed. # -- # FIXME: I will be ignored. # ++ # This will also get parsed. # :stopdoc: # Everything here on out will be ignored.
  38. 88.

    You can link to headings inside of documentation by following

    the destination class or method name by an @ and the heading name. ## # See also RDOC::Markup@Links Will be a link and look something like this: “Links at RDoc::Markup”.
  39. 90.

    RDoc supports other markup types, such as markdown. It can

    use the file extension for the included file. Or you can specify the markup type inline: ## # :markup: markdown # Your markdown comments go here.. class MyClass # ...