Fork documenting-ruby's fork of Ruby on github.
Clone your new repo:
git clone firstname.lastname@example.org: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.
To help others know what you're documenting, open an issue on documenting-ruby's fork of Ruby.
Write your new documentation.
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.
<code>foo.bar</code>, you can use
+foo.bar+. It doesn't always work on operators, so use
#foowhen 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
rdoc -o tmpdoc lib/drb*
Preview your new documentation in
Tip: You can use the
adsfgem 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).
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
.patch to the
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.
Here is an example of a documentation patch that Eric Hodel added. You can reference this for style.