Node.js Documentation Problems

By Xah Lee. Date: . Last updated: .

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');
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.