Covered In This Episode:
- Comments
- RDoc
Transcript:
Hello Everybody and welcome to Programming With Ruby Episode 12,
Documentation. I’m Tyler and this video is brought to you by
manwithcode.com.
In this episode I will be talking about documenting your code, more
specifically with comments, and using the tool rdoc.
This should be a short show, so lets get started!
Comments
You’ve seen comments throughout these video tutorials. They were the
lines with the hash mark that are ignored by Ruby.
Comments are generally used to explain code to other developers
(including yourself). Ruby already makes code very easy to understand
in the first place. You can also help this by naming your methods and
variables sensibly. But there are times when this is not enough.
Sometimes you end up doing something very complicated, such as a long
regular expression, some SQL magic, or any other possibly difficult to
understand piece of code. Those can be times when comments are needed.
Comments are also needed for when you are making code for other
developers to use. When they are using your code and not developing it
along with you, they can care less about finding how it works. They
just want a comment that can tell them what your class/method/piece of
code/whatever does, and how to make it do it.
Tools like rdoc can help you make your code’s documentation even
better, and that is what we are going to talk about next.
Rdoc
Rdoc should be installed already from when you installed ruby. If not
you can install it via rubygems or your platforms package manager.
Rdoc is a tool that generates very nice looking documentation for your
projects.
First just run the command rdoc in a directory with code files in it.
rdoc will create a folder named “doc” and your documentation will be
that folder. If you go into doc and open up index.html in your
browser, you will see the generated documentation.
You will probably notice that rdoc didn’t pick up any of the comments
inside your code, only those right above the definitions of classes,
methods, or modules.
You may also notice that the descriptions might not be formatted very
well. You can spice it up by using rdoc markup found at:
http://rdoc.rubyforge.org/RDoc.html
I’m not going to go too much farther into rdoc, as it is not an
essential tool for development. It can be, however, very useful. So
please take some time to learn more about it!
This brings us to the end of the show.
Please don’t forget to donate!
If you have any questions, comments, or suggestions you can leave them
in the comment box below or email me at tyler@manwithcode.com
Thank you very much for watching, goodbye!