[doc minor] Add code docs. Make new search API more consistent with e…

…xisting style

lib/loggly/core.js

@@ -32,11 +32,6 @@ var Loggly = exports.Loggly = function (config) {
   this.config = config;
 };
 
-Loggly.prototype.search = function (q, cb) {
-
-  return new Search(q, this, cb);
-};
-
 //
 // function log (callback) 
 //   logs args to input device
@@ -69,6 +64,23 @@ Loggly.prototype.log = function (inputId, msg, callback) {
   return emitter; 
 };
 
+//
+// function search (query, callback)
+//   Returns a new search object which can be chained
+//   with options or called directly if @callback is passed
+//   initially.
+//
+// Sample Usage:
+//
+//   client.search('404')
+//         .meta({ ip: '127.0.0.1' })
+//         .context({ rows: 100 })
+//         .run(function () { /* ... */ });
+//
+Loggly.prototype.search = function (query, callback) {
+  return new Search(query, this, callback);
+};
+
 //
 // function getInputs ([raw], callback) 
 //   Returns a list of all inputs for the authenicated account
@@ -109,7 +121,6 @@ Loggly.prototype.getInput = function (name, callback) {
   });
 };
 
-
 //
 // function addDevice (inputId, address, callback) 
 //   Adds the device at address to the input specified by inputId

lib/loggly/search.js

@@ -1,50 +1,68 @@
-
 /*
- * core.js: chainable search functions for Loggly
+ * search.js: chainable search functions for Loggly
  *
- * (C) 2010 hij1nx
+ * (C) 2010 Nodejitsu Inc.
  * MIT LICENSE
  *
  */
 
+var interns = require('./interns');
+
 //
-// Sample Usage:
-//
-// client
-//   .search('404')
-//   .meta({ ip: '127.0.0.1' })
-//   .context({ rows: 100 })
-//   .run(function () { /* ... */ });
+// function Search (query, client, callback) 
+//   Chainable search object for Loggly API
 //
-
-var Search = exports.Search = function(query, client, callback) {
-
+var Search = exports.Search = function (query, client, callback) {
   this.query = query;
   this.client = client;
+
+  // If we're passed a callback, run immediately.
   if (callback) {
-    this.run(callback);
+    this.callback = callback;
+    this.run();
   }
 };
 
-Search.prototype.meta = function (cfg) {
-
-  this.meta = cfg;
+//
+// function meta (meta)
+//   Sets the appropriate metadata for this search query:
+//   e.g. ip, inputname
+//
+Search.prototype.meta = function (meta) {
+  this.meta = meta;
   return this;
 };
 
-Search.prototype.context = function (cfg) {
-
-  this.context = cfg;
+//
+// function context (context)
+//   Sets the appropriate context for this search query:
+//   e.g. rows, start, from, until, order, format, fields
+//
+Search.prototype.context = function (context) {
+  this.context = context;
   return this;
 };
 
+//
+// function run (callback) 
+//   
+//
 Search.prototype.run = function (callback) {
-
+  // Trim the search query 
+  this.query.trim();
+
+  // Update the callback for this instance if it's passed
+  this.callback = callback || this.callback;
+  if (!this.callback) {
+    throw new Error('Cannot run search without a callback function.');
+  }
+
+  // If meta was passed, update the search query appropriately
   if (this.meta) {
-    this.query.trim();
     this.query += ' ' + qs.unescape(qs.stringify(meta, ' ', ':'));
   }
 
+  // Set the context for the query string
   this.context = this.context || {};
   this.context.q = this.query;
 
@@ -53,9 +71,9 @@ Search.prototype.run = function (callback) {
     auth: this.client.config.auth
   };
 
-  interns.loggly(searchOptions, callback, function (res, body) {
-    cb(null, JSON.parse(body));
+  interns.loggly(searchOptions, this.callback, function (res, body) {
+    this.callback(null, JSON.parse(body));
   });
-
+  
   return this;
 };