socket.end() can take a callback function

[GloriaAnholt]

Checklist

• [X ] documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

Documentation

Description of change

It's undocumented, but socket.end can take a callback function. We discovered this
by passing Mocha's done() callback in, and socket.end does indeed call the function.

You can see the callback code in node/lib/net.js starting line 285
https://github.com/nodejs/node/blob/68ba9aa0fb6693a1fb5dd114a3ddbe447517c0dd/lib/net.js

// Provide a better error message when we call end() as a result
// of the other side sending a FIN.  The standard 'write after end'
// is overly vague, and makes it seem like the user's code is to blame.
function writeAfterFIN(chunk, encoding, cb) {
  if (typeof encoding === 'function') {
    cb = encoding;
    encoding = null;
  }

  var er = new Error('This socket has been ended by the other party');
  er.code = 'EPIPE';
  // TODO: defer error events consistently everywhere, not just the cb
  this.emit('error', er);
  if (typeof cb === 'function') {
    process.nextTick(cb, er);
  }
}

I'm sure my wording isn't quite right, but please do add the optional [, callback] to the docs!

[bnoordhuis]

net.Socket#end() doesn't take a callback but it's possible you were dealing with a derived class that does. The code you highlight is monkey-patched over socket.write (not socket.end) when the socket is closed/closing.

[jasnell]

Closing as there does not appear to be anything to do.
Thank you @GloriaAnholt for the contribution nevertheless.