Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Document Public/Private API #23

Open
skeggse opened this Issue Oct 1, 2013 · 4 comments

Comments

Projects
None yet
2 participants
Contributor

skeggse commented Oct 1, 2013

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() {
  ...
};
Owner

squaremo commented Oct 1, 2013

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".

Contributor

skeggse commented Oct 1, 2013

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.

Owner

squaremo commented Oct 1, 2013

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.

Contributor

skeggse commented Oct 1, 2013

That'd be awesome, thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment