Search this site


Metadata

Articles

Projects

Presentations

How not to write documentation.

I've grown accustomed to ruby having poorly accessible documentation. What I mean by 'poorly accessible' is the fact that ri Array gives me a list of things Array can do (which is nice), but to actually find out about Array.delete I have to run ri Array.delete. Further, the online ruby documentation is better, but not great, but is somehow strangely different from simply the rdoc itself. I got used to Python's often-helpful ways of pydoc showing you what appears to be "as much as possible" when you pydoc a class, module, or method.

Maybe I'm doing it wrong. Either way, the following is annoying and unhelpful. While it tells me the arguments that should be passed, and what is returned, it doesn't help me really know more about the function. Luckly, I'm already familiar with select from other languages.

snack(~) % ri IO.select
------------------------------------------------------------- IO::select
     IO.select(read_array 
     [, write_array 
     [, error_array 
     [, timeout]]] ) =>  array  or  nil
------------------------------------------------------------------------
     See +Kernel#select+.
Ok, fine... Let's look at Kernel#select.
snack(~) % ri Kernel#select
---------------------------------------------------------- Kernel#select
     IO.select(read_array 
     [, write_array 
     [, error_array 
     [, timeout]]] ) =>  array  or  nil
------------------------------------------------------------------------
     See +Kernel#select+.
*sigh*