Where do I find documentation for Ruby, Perl, and PHP libraries? · 10 August 2008, 10:54

In this post I give a quick overview and comparision of documentation tools and resources for the three languages I am developing with the most these days: PHP, ruby, and perl. I enjoy developing with all of these languages, but some are easier than others when it comes to documentation.


CPAN – The Comprehensize Perl Archive Network. The vast majority of perl libraries are posted to CPAN. CPAN has a nice web-based search search interface as well as a great command line interface as well (the “cpan” command is a part of most perl distributions, if it is not on your system just type perl -MCPAN -e shell).

All built-in functions are well-documented in POD (Plain Old Documentation) format and available for reading using the perldoc tool. For example, to see the documentation for the open function, just type

perldoc -f open

As much as perl gets bashed for being noisy, confusing, etc, it by far has the best user-contributed documentation of the three languages I am covering in this post and being able to search using namespaces and regular expressions from the command line is a huge win.

Maybe it is because it is so flexible and because it has the potential to be confusing that user-supplied documentation is so well done?


PHP has a terrific set of online manuals for built-in libraries, to read them just enter the URL, for example

to see the documentation for the fopen command. A terrific feature of this web site is that all pages allow for user comments, these comments oftern provide terrific examples and explanations of quirks or hints to be mindful of with a given function. Good stuff.

For 3rd party libraries, things are not quite as nice as CPAN. First check, you might find documentation for the library there, more likely than not you will find a link to the documentation that the developer is hosting elsewhere.

If the PEAR repository fails, use Google.


Finding documentation with Ruby is interesting. For core libraries all documentation can be found online at Core documentation is excellent.

3rd party library documentation is good, but in my opinion much of it is not nearly as comprehensive or easy to find as it is for perl or PHP. Maybe this is because much new development still happens in Asia and the asian developers do not have the time nor interest to port documentation to English (which I can completely understand).

Most ruby libraries are hosted on Unfortunately, as with PHP’s PEAR, most developers do not take the time to extract / post documentation to the documentation section of any of the projects. Some leave links to the sites they have created in the documentation section of the project, some use the rubyforge web site URL, e.g.

To document their projects online. In either case, the documentation seems to be much more complete when it is posted online than when it is installed with the gem. I find that it is usually much easier to use the web-based documentation than it is to try and read it from the command line with ri.

I also find that with Ruby, Google searching is required to find examples and often blogs are the best sources of examples and annotations for libraries. I am very very grateful to the many ruby users who post examples on their blogs, however, it is a litte disappointing to not have a centralized place for this information.

Finally, I find it annoying (and I know, if I do not like it, I should contribute) that the gem tool does not allow an end user to search by namespace .. how the heck am I supposed to know a gem name before I search for the name space? Google, I know :).

Ruby hates the command line for documentation.


— Max Schubert



Textile Help