21 Mar 2005
(updated 21 Mar 2005 at 23:14 UTC) »
One of the things I miss when I am programming in something that is not Perl is pragmatic library documentation accompanying specifications, architecure descriptions, or whatever you want to put there. I don't understand why you are supposed to infer the usage of some library from the spec so often in Java, C, Python, etc. From my experience, in general the Perl conventions are ahead of any other I know.
When you read the documentation of a Perl module you see:
- How the module is used
- The module specification
The first part is code, right there, no English. By convention it goes in a section called SYNOPSIS which is the first one you see after the one-line description and the table of contents. See for instance the SYNOPSIS of IO::All. You get the picture at a glance. Not the details, to know the details or get the complete interface you then read what you need below, but you already have context.
To give a recent example of lack of pragmatism, look at the most recent documentation of the standard Python module CGIHTTPServer. Oh man, how on earth do I set up a server with that class? One reads that page and thinks: Hum, well, let's try the docs of its parent class. Ha, not so easy dude! Have a look at SimpleHTTPServer. Nope, you find a similar page. OK, be patient, maybe we'll have more luck with the documentation of BaseHTTPServer? Now something! At last! Some example!
But now, how to translate that example to CGIHTTPServer? You backtrack the links and try to figure it out. Finally you come to produce:
handler_class = CGIHTTPServer.CGIHTTPRequestHandler
server_address = ('', 8080)
httpd = BaseHTTPServer.HTTPServer(server_address, handler_class)
which curiously enough does not
instantiate a CGIHTTPServer