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}. 〔➤ programing documentation idiocy collection

Node's doc is minimal, to the point, and clean, functional. No author masturbation (as do Python 〔➤ Python Documentation Problems〕), no juvenile jokes (as do unix, perl, python). 〔➤ Perl Documentation: the Key to Perl〕 〔➤ 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 ƒ).

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.

discuss

blog comments powered by Disqus