Man With Code 👨‍💻

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 [email protected] Thank you very much for watching, goodbye!