Node.js Documentation Problems

some quick notes about problems of Node.js doc.

Node's doc is excellent, in comparison to others such as {unix, perl, python}. [see programing documentation idiocy collection]

Node's doc is minimal, to the point, and clean, functional. No author masturbation (as do Python [see Python Documentation Problems]), no juvenile jokes (as do unix, perl, python). [see Perl Documentation: the Key to Perl] [see Idiocy of Computer Language Docs: Unix, Python, Perl, Haskell]

However, it is not without problem. Here's a quick example.

For example, if you are writing a chat server, there's this function net.createServer(callback_f).

It takes a function argument as a callback. It returns a server object. The callback function is called when “connect” event happens. And a “socket” object is passed to it.

you can read it in the doc net, and it has this sample code of a simple chat server:

var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
  console.log('server connected');
  c.on('end', function() {
    console.log('server disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
  console.log('server bound');
});

Note that the “c” is the arg passed to the callback function. But what exactly is “c”? It's impossible to find out just by this doc.

Note there's c.on, so there's a “on” method for this “c” thing, but nowhere in the doc you see “on” method mentioned. From experience and other sources, you find out that this “c” is a socket object, and this socket object is a child of “event” object. So, you get to the event module doc page at Events. There, you see the “.on()” method.

But now, look at the sample server code, there's c.write(). The only thing close in the doc is socket.write(data, [encoding], [callback]), from which, you infer that the “c” in c.write() is a socket object.

look at the sample server code again, there's c.pipe(). This “pipe()” method not in the Events object doc page. Nor will you find it anywhere. So, where is this “pipe()” method documented? How's user lead to it?

here's some other generic Node doc problems.

• no cross-links in the doc. For example, when talking about events, it should provide a link to the events module.
• sample code doesn't have syntax coloring. Syntax coloring makes it much more readable.
• thru-out the doc, you see the dot notation a.b.c. However, for some, the “a” part is literal, while others, the “a” part is any variable. For example, compare: process.version and net.createServer(). You can't tell, whether the “process” or “net” there is literal or just a variable name that you happened to use. This is quite confusing at syntax level. It would be better, that for those that's a variable, indicate it with angle brackets, like this net.createServer. [see OOP Dot Notation, Dot Before Data or After?]
• in general, what's passed to the callback function is not specifically mentioned. That is, the doc doesn't say what object exactly is passed.
• in general, the return value of a function is not specified exactly.

[discuss https://plus.google.com/+XahLee/posts/dh6oFLSv3PS]