Merge branch 'doc_imporovements'

Author: benjaminws

lib/frame.js

@@ -1,40 +1,47 @@
-/*
-    frame.js - Frame object
+// ## frame
+//
+// The `Frame` module provides an object representation of a `Stomp` frame.
+//
+// ### frame.Frame
+//
+// An instance of the `Frame` object.
+//
+//     var frame = new frame.Frame();
+//
+// ### frame.Frame.build_frame()
+//
+// Build a frame object from an object of arguments.
+//
+//     var args = {
+//         command: '',
+//         headers: {},
+//         body: ''
+//     };
+//
+//     this_frame = frame.build_frame(args);
+//
 
-    Copyright (c) 2010, Benjamin W. Smith
-    All rights reserved.
 
-    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
-      other materials provided with the distribution.
-    * Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software
-      without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
-    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-*/
-
-/**
- * Frame - Object representation of a STOMP frame
- */
+//
+// ## Frame - Object representation of a STOMP frame
+//
 function Frame() {
     this.command = null;
     this.headers = null;
     this.body = null;
 };
 
-/**
- * Build frame based on arguments provided
- * @param {Object} arguments needed to build frame (command, headers, body?)
- * @param {Bool} Indicate that you wish to get a receipt (set receipt header)
- * @return {Object} Frame object
- */
+//
+// ## Frame.build_frame(args, want_receipt)
+//
+// **Build frame based on arguments provided**
+//
+// Takes arguments object needed to build frame (command, headers, body?)
+//
+// Takes boolean to indicate that you wish to get a receipt (set receipt header)
+//
+// Returns an object representing a frame
+//
 Frame.prototype.build_frame = function(args, want_receipt) {
     var receipt_stamp = null;
 
@@ -56,10 +63,13 @@ Frame.prototype.build_frame = function(args, want_receipt) {
     return this;
 };
 
-/**
- * String representation of Frame object
- * @return {String} - Frame as string
- */
+//
+// ## Frame.as_string()
+//
+// **String representation of Frame object**
+//
+// Returns `Frame` as string
+//
 Frame.prototype.as_string = function() {
     var header_strs = [],
         frame = "",
@@ -68,15 +78,16 @@ Frame.prototype.as_string = function() {
         body = this.body;
 
     for (var header in headers) {
-        header_strs.push(header + ':' + headers[header]);
+       header_strs.push(header + ':' + headers[header]);
     }
 
     frame += command + "\n";
     frame += header_strs.join("\n");
     frame += "\n\n";
 
-    if(body)
+    if(body) {
         frame += body;
+    }
 
     frame += '\x00';
 

lib/stomp.js

@@ -1,24 +1,24 @@
-/*
-    stomp.js - STOMP Protocol in node.js
-
-    Copyright (c) 2010, Benjamin W. Smith
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or
-      other materials provided with the distribution.
-    * Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software
-      without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
-    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-*/
+// ## stomp
+//
+// The `Stomp` module provides you with a client interface for interacting with STOMP messaging brokers
+//
+// ### stomp.Stomp
+//
+// An instance of the `Stomp` object.  Initialized like so:
+//
+//     var stomp_args = {
+//         port: 61613,
+//         host: 'localhost',
+//         debug: false,
+//         login: 'guest',
+//         passcode: 'guest',
+//     };
+//
+//     var client = new stomp.Stomp(stomp_args);
+//
+// If debug is set to true, extra output will be printed to the console.
+
+// ## Helpers to handle frames, and do parsing
 
 var net = require('net'),
     tls = require('tls'),
@@ -29,6 +29,7 @@ var net = require('net'),
     utils = new stomp_utils.StompUtils(),
     log = null;
 
+
 function parse_command(data) {
     var command,
         this_string = data.toString('utf8', 0, data.length);
@@ -231,10 +232,11 @@ function send_frame(stomp, _frame) {
     return true;
 };
 
-/**
- * Stomp - Client API
- * @param {Object} args
- */
+//
+// ## Stomp - Client API
+//
+// Takes an argument object
+//
 function Stomp(args) {
     this.port = args['port'] || 61613;
     this.host = args['host'] || "127.0.0.1";
@@ -250,24 +252,27 @@ function Stomp(args) {
     this['client-id'] = args['client-id'] || null;
 };
 
+// ## Stomp is an EventEmitter
 Stomp.prototype = new process.EventEmitter();
 
-/**
- * Begin connection
- */
+// ## Stomp.connect()
+//
+// **Begin connection**
+//
 Stomp.prototype.connect = function() {
     _connect(this);
 };
 
-/**
- * Handle frame based on type
- * @param {Object} Frame Object
- */
+// ## Stomp.handle\_new_frame()
+//
+// **Handle frame based on type. Emit events when needed.**
+//
+// Takes a `Frame` object
+//
 Stomp.prototype.handle_new_frame = function(this_frame) {
     switch (this_frame.command) {
         case "MESSAGE":
             if (utils.really_defined(this_frame.headers['message-id'])) {
-                // if a subscription to the destination queue exists, fire callback
                 if (this_frame.headers !== null && this_frame.headers.destination !== null && this._subscribed_to[this_frame.headers.destination] !== null) {
                     var subscription = this._subscribed_to[this_frame.headers.destination];
                     if (subscription.enabled && subscription.callback !== null && typeof(subscription.callback) == 'function') {
@@ -294,17 +299,24 @@ Stomp.prototype.handle_new_frame = function(this_frame) {
     }
 };
 
-/**
- * Disconnect from STOMP broker
- */
+//
+// ## Stomp.disconnect()
+//
+// **Disconnect from STOMP broker**
+//
 Stomp.prototype.disconnect = function() {
     _disconnect(this);
 }
 
-/**
- * Subscribe to destination (queue or topic)
- * @param {Object} headers
- */
+//
+// ## Stomp.subscribe()
+//
+// **Subscribe to destination (queue or topic)**
+//
+// Takes a header object
+//
+// Takes a callback function
+//
 Stomp.prototype.subscribe = function(headers, callback) {
     var destination = headers['destination'];
     headers['session'] = this.session;
@@ -313,10 +325,13 @@ Stomp.prototype.subscribe = function(headers, callback) {
     this.log.debug('subscribed to: ' + destination + ' with headers ' + sys.inspect(headers));
 };
 
-/**
- * Unsubscribe from destination (queue or topic)
- * @param {Object} headers
- */
+//
+// ## Stomp.unsubscribe()
+//
+// **Unsubscribe from destination (queue or topic)**
+//
+// Takes a header object
+//
 Stomp.prototype.unsubscribe = function(headers) {
     var destination = headers['destination'];
     headers['session'] = this.session;
@@ -325,50 +340,67 @@ Stomp.prototype.unsubscribe = function(headers) {
     this.log.debug('no longer subscribed to: ' + destination);
 };
 
-/**
- * Acknowledge received message
- * @param {String} message id to acknowledge
- */
+//
+// ## Stomp.ack()
+//
+// **Acknowledge received message**
+//
+// Takes a string representing the message id to ack
+//
 Stomp.prototype.ack = function(message_id) {
     send_command(this, 'ACK', {'message-id': message_id});
     this.log.debug('acknowledged message: ' + message_id);
 };
 
-/**
- * Begin transaction
- * @return {String} generated transaction id
- */
+//
+// ## Stomp.begin()
+//
+// **Begin transaction**
+//
+// Return a string representing the generated transaction id
+//
 Stomp.prototype.begin = function() {
     var transaction_id = Math.floor(Math.random()*99999999999).toString();
     send_command(this, 'BEGIN', {'transaction': transaction_id});
     this.log.debug('begin transaction: ' + transaction_id);
     return transaction_id;
 };
 
-/**
- * Commit transaction
- * @param {String} transaction id generated by stomp.Stomp.begin()
- */
+//
+// ## Stomp.commit()
+//
+// **Commit transaction**
+//
+// Takes a string representing the transaction id generated by stomp.Stomp.begin()
+//
 Stomp.prototype.commit = function(transaction_id) {
     send_command(this, 'COMMIT', {'transaction': transaction_id});
     this.log.debug('commit transaction: ' + transaction_id);
 };
 
-/**
- * Abort transaction
- * @param {String} transaction id generated by stomp.Stomp.begin()
- */
+//
+// ## Stomp.abort()
+//
+// **Abort transaction**
+//
+// Takes a string representing the transaction id generated by stomp.Stomp.begin()
+//
 Stomp.prototype.abort = function(transaction_id) {
     send_command(this, 'ABORT', {'transaction': transaction_id});
     this.log.debug('abort transaction: ' + transaction_id);
 };
 
-/**
- * Send MESSAGE to STOMP broker
- * @param {Object} headers required (destination is required)
- * @param {Bool} do you want a receipt of the message sent?
- * @return {Object} Frame object of message sent
- */
+//
+// ## Stomp.send()
+//
+// **Send MESSAGE to STOMP broker**
+//
+// Takes a header object (destination is required)
+//
+// Takes a boolean requesting recipt of the sent message
+//
+// Returns a `Frame` object representing the message sent
+//
 Stomp.prototype.send = function(headers, want_receipt) {
     var destination = headers['destination'],
     body = headers['body'] || null;