I will expound my findings "beneath the skin" in future posts, but I ran across something today so telling of my general experience, syntax aside.
Look at these two urls. Both are from the official* standard library documentation for the respective language.
- Ruby - http://www.ruby-doc.org/stdlib/libdoc/digest/rdoc/classes/MD5.html
- Python - http://docs.python.org/lib/module-md5.html
While this is just one example, I've run across it sooooooooo many times in the last three years. It's such a sad state of affairs that the official Ruby web site doesn't even *have* a documentation section of its own...it simply links to a collection of tutorials and third-party docs. Ruby-doc.org, which I pulled the above link from, takes the same approach, but includes the generated rdoc for the core and std libs. This rdoc is often, as demonstrated above, simply empty method prototypes.
It's simply tragic that such a useful and appealing tool has such shoddy documentation.
18 comments:
The ruby version doesn't even list real methods. MD5 is a class object with several useful methods, none of them documented:
irb(main):001:0> require 'digest/md5'
=> true
irb(main):002:0> Digest::MD5.public_methods(false)
=> ["digest", "file", "hexdigest", "allocate", "superclass", "new"]
irb(main):003:0> quit
$ ri MD5.digest
Nothing known about MD5.digest
$ ri MD5.hexdigest
Nothing known about MD5.hexdigest
And so on...
Ruby and Python share many similarities, and they don't stop just at the language. Both are open source, and both arguably fall into the camp of having a BDFL (a Benevolent Dictator For Life, for the uninitiated). Some would argue that Linux also falls into this category.
While much of the inspiration, direction and sweat equity has been (originally) sourced from a single person [Matz, Guido, Linus], as open source projects, they and their accompanying documentation belong to their respective communities.
The qualitative differences you're pointing out in comparing the documentation of a python class to a ruby class are certainly valid. The distinction I would make, however, is that this is not a problem with the Ruby language, but falls on the Ruby community of which we all consider ourselves a part.
To that end, the solution is not only within reach, but it's our responsibility to carry out. Instead of pointing blame at Ruby, let's look to ourselves and ask not what has Ruby done for me, but what can I do for Ruby? (apologies to JFK ;)
If you search many of the popular Ruby newsgroups you'll find this topic has received much attention lately. I do hope that parlays into an organized effort, to which I'm happy to participate, in providing better documentation, in the public domain(!) that serves us, and our favorite language, all at once.
While I appreciate your mentioning this, and there are a lot of areas where Ruby is poorly documented, I think picking out one of the few places where documentation is non-existent is a little unfair. Even further, there are a number of things in Python that aren't documented, but the documentation tools skip them if there isn't any documentation. :)
We're working on fixing this and other documentation faults.
A few months ago, I printed out Python's MD5 docs and stuck them in the Ruby section of my 3-ring binder. Oy.
My "favorite" piece of undocumented Ruby is Config::CONFIG (rbconfig).
@mr. neighborly:
I challenge you to point out one...that's right...just one...piece of Python's core or standard libraries that isn't documented. Seriously...
For a language that is so "easy to read" who needs documentation?
Are you all really wasting time in this pointless discussion? C'mon, grow up. Brian said it all. 'Nuff said.
That's why there is much interest and lots of activities in various efforts like Ruby Specification Wiki and RubySpec conformance test suites, etc. Also, new book "The Ruby Programming Language", co-authored by Matz, serves as a good description/specification of Ruby Language.
Mr Neighbourly said "Even further, there are a number of things in Python that aren't documented, but the documentation tools skip them if there isn't any documentation. :)".
Can you give some examples of the "number of things" in Python that are not documented? That sounds like FUD to me.
Python is missing some documentation, but by-and-large I would say most things are well documented.
Consider this session ( feel free to follow along ina a python session of your own ):
$ python
...
>>> import md5
>>> help( md5 )
>>> hasher = md5.new()
>>> hasher.update( 'hello' )
>>> hasher.hexdigest()
'5d41402abc4b2a76b9719d911017c592'
>>>
That's probably how about 90% of my dealings with new modules goes -- import x, help( x ), use x.
FREE Python docs & books. Search FSF's free books list for Python & Zope, then search it for Ruby & Rails. No comparison, pals.
Glenn said "That's probably how about 90% of my dealings with new modules goes -- import x, help( x ), use x."
Even better, give ipython a try. This gives you direct access to the python docstrings, context sensitive tab completion, and much much more.
Here is the ipython equivalent of your example (N.B. [tab] means hit the tab key):
import x[tab]
# (lists and cycles through all the modules on the path that start with x)
x?
# (prints information about x, including the file it is defined in and its docstring)
x??
# (prints even more information about x, including the syntax highlighted source code)
x.[tab]
# (lists and cycles through the methods & attributes on x)
x.foo?
# (prints info on the foo method or attribute of x)
and so on. You can also use the same help() system as in the regular python interpreter.
I hardly ever need to refer to the Python docs, excellent though they are, since it is usually quicker and easier to ask ipython.
Totally love how this came out--looks like something from an editorial. Love the feather earrings..
Çok güzel bir site gerçekten.
blog olarak güzel bir site.
Çok güzel emeği geçen arkadaşlara teşekkürler.
Czech Casting
Czech Massage
sohbet
mobil sohbet
Post a Comment