Document Public/Private API

[skeggse]

It would be nice, for reference, if the code itself contained more documentation. The comments are excellent, but more organization and a clearer specification of whether a method/function is public or private would be nice.

Consider using JavaDoc/JSDoc syntax:

/**
 * Construct a new Connection object.
 *
 * @param {Stream} underlying The stream the Connection should bind to.
 * @constructor
 */
function Connection(underlying) {
  ...
}

/**
 * Close with a reason and a 'code'. I'm pretty sure RabbitMQ totally ignores
 * these; maybe it logs them. Returns a promise that will be resolved when the
 * CloseOk has been received; NB the 'close' event will be emitted once the
 * underlying stream is ended.
 *
 * @param {string} reason
 * @param {number}
 * @public
 */
C.closeBecause = function(reason, code) {
  ...
};

/**
 * A close has been initiated. Repeat: a close has been initiated. This means we
 * should not send more frames, anyway they will be ignored. We also have to
 * shut down all the channels.
 *
 * @private
 */
C.stop = function() {
  ...
};

[squaremo]

I played around with jsdoc (and maybe some other similar?) and had a bad time, mainly because it thinks of things in terms of classes and couldn't understand which methods belonged to which "classes".

[skeggse]

I'm not necessarily recommending you use a tool to convert your source into more readable documentation. I don't. But when I'm looking at code I wrote a year ago and I don't want to figure out what parts are public and which are private having some amount of inline documentation has been very valuable.

[squaremo]

Ah yes I meant to say to that bit, "good point". I'm going to go through at some point and give the "private" methods leading underscores, at least.

[skeggse]

That'd be awesome, thanks!

[soryy708]

New JS feature: Private class features

private class members can be created by using a hash # prefix. The privacy encapsulation of these class features is enforced by JavaScript itself.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields

[cressie176]

Hi @soryy708,
Thanks for the suggestion, however amqplib supports node 10 and above, meaning we are not able to introduce some of the more recent JavaScript features.