How To Document Ruby

Getting Set Up

Fork documenting-ruby's fork of Ruby on github.

Clone your new repo:

git clone git@github.com:YOUR_NAME/ruby.git

Add the upstream remote:

git remote add upstream https://github.com/documenting-ruby/ruby.git
git fetch upstream
git merge upstream/trunk

Choose some code to document. You can use our suggestions for code to document or follow these instructions to generate your own list of undocumented code. Check documenting-ruby's fork of Ruby issues for a list of documentation other people are working on.

Get a list of undocumented code (you must have rdoc >= 3.3 for this to work):

rdoc -C1 > documentation_coverage.txt

You can also pass a list of files to check the documentation coverage, if you already have something in mind:

rdoc -C1 lib/drb* > documentation_coverage.txt

Search for "is not documented" in "documentation_coverage.txt". Find something that interests you, and document it. You can see how much of Ruby is documented by looking at the stats at the bottom of the file.

We have generated a few of these reports for various areas of the MRI source, see our undocumented coverage report.

top

Documenting

To help others know what you're documenting, open an issue on documenting-ruby's fork of Ruby.

Write your new documentation.

• For writing top-level docs in C files, look for Document-class or rb_define_class (may be towards the bottom of the file.) For writing method docs, look for rb_define_method, and then look for the function it uses.
• To emit <code>foo.bar</code>, you can use +foo.bar+. It doesn't always work on operators, so use <code>==</code>, not +==+.
• Use #foo when writing about the foo method - it'll make a link to foo's documentation. Foo.new(42) will create a link to the constructor's docs.

Generate your new HTML documentation:

rdoc -o tmpdoc PATH/TO/YOUR/FILES

This for example will document all drb files:

rdoc -o tmpdoc lib/drb*

Preview your new documentation in tmpdoc/index.html.

Tip: You can use the adsf gem to serve your files locally, similar to gem server. Install the gem and cd tmpdoc && adsf. It defaults to port 3000.

Once it looks good delete your extra files:

rm -rf tmpdoc documentation_coverage.txt

Add your documentation change:

git add .

Commit your documentation change:

git commit -m "adding documentation for WHAT_YOU_CHANGED"

Submit a pull request to documenting-ruby's fork if you want a quality review, or need help creating a patch to submit to Ruby Core. Or if you have something that's ready to go, you can submit the patch yourself (see instructions below).

top

Instructions for creating your own patch

Create a patch to submit to ruby-core:

git format-patch HEAD~1

If you're having trouble generating a patch, but you have committed your changes to github, simply append .patch to the end of your commit. For example, if you take the following commit and add .patch to the url you can save this page as a patch and upload it to the bug tracker.

Open a new ticket on RedMine and submit your patch (will be called something like "0001-*.patch" in the root directory of the project). You'll need to sign up if you haven't before. Assigning drbrain or zzak to the ticket should help make sure your patch is pulled in a timely manner.

Additional Information

Here is an example of a documentation patch that Eric Hodel added. You can reference this for style.

Thanks to Steve Klabnik for his excellent post on which most of this information is based.