tomdoc'd

lib/index.js

@@ -6,6 +6,23 @@ var sys = require('sys'),
 
 // Creates a streaming connection with twitter, and pushes any incoming
 // statuses to a tweet event.
+//
+// options - optional Object that specifies custom configuration values.
+//
+// Valid option keys:
+//
+// port      - Integer of the streaming api connection port.  Defaults to 80.
+// host      - String of the streaming api host.  Defaults to 'stream.twitter.com'.
+// path      - String of the base path for the request.
+// action    - String part of the URL that specifies what to query for.
+// track     - Array of keywords to filter.  See track()
+// following - Array of userIDs to filter.  See follow()
+// locations - Array of lat/long tuples.  See location()
+// params    - Extra HTTP params Object to send with the request.
+// user      - String Twitter login name or email.
+// password  - String Twitter password.
+//
+// Returns TwitterNode instance.
 var TwitterNode = exports.TwitterNode = function(options) {
   if(!options) options = {}
   this.port          = options.port      || 80
@@ -20,7 +37,8 @@ var TwitterNode = exports.TwitterNode = function(options) {
   this.password      = options.password
   this.headers       = {"User-Agent": 'Twitter-Node: node.js streaming client'}
   this.debug         = false
-  this.setupJSONParser();
+  this.parser = new parser.instance();
+  this.parser.addListener('object', this.processJSONObject(this))
   if(options.headers) {
     // FIXME: process.mixin depreciating
     process.mixin(this.headers, options.headers)
@@ -29,21 +47,41 @@ var TwitterNode = exports.TwitterNode = function(options) {
 
 TwitterNode.prototype = Object.create(process.EventEmitter.prototype);
 
-// track the following keyword
-// http://apiwiki.twitter.com/Streaming-API-Documentation#track
+// Track the following keyword.  If called multiple times, all words are sent
+// as a comma-separated parameter to Twitter.
+//
+// See: http://apiwiki.twitter.com/Streaming-API-Documentation#track
+//
+// word - String word to track.
+//
+// Returns nothing.
 TwitterNode.prototype.track = function(word) {
   this.trackKeywords.push(word);
 }
 
-// follow the given twitter user (specified by their userID, not screen name)
-// http://apiwiki.twitter.com/Streaming-API-Documentation#follow
+// Follow the given twitter user (specified by their userID, not screen name)
+// If called multiple times, all userIDs are sent as a comma-separated
+// parameter to Twitter.
+//
+// See: http://apiwiki.twitter.com/Streaming-API-Documentation#follow
+//
+// userID - Integer userID to track.
+//
+// Returns nothing.
 TwitterNode.prototype.follow = function(userId) {
   this.following.push(userId);
 }
 
-// match tweets in the given bounding box.
-// lng1 and lat1 are the southwest corner
-// http://apiwiki.twitter.com/Streaming-API-Documentation#locations
+// Match tweets in the given bounding box.
+//
+// See: http://apiwiki.twitter.com/Streaming-API-Documentation#locations
+//
+// Example: location(-122.75, 36.8, -121.75, 37.8) // SF
+//
+// lng1, lat1 - southwest corner of the bounding box.
+// lng2, lat2 - northeast corner.
+//
+// Returns nothing.
 TwitterNode.prototype.location = function(lng1, lat1, lng2, lat2) {
   this.locations.push(lng1, lat1, lng2, lat2)
 }
@@ -69,7 +107,7 @@ TwitterNode.prototype.stream = function() {
 
     response.setBodyEncoding('utf8');
     response.addListener('data', function(chunk) {
-      twit.parser.receive(chunk);
+      twit.receive(chunk);
     });
     response.addListener('end', function() {
       twit.emit('end',   this);
@@ -80,11 +118,13 @@ TwitterNode.prototype.stream = function() {
   return this;
 };
 
-TwitterNode.prototype.setupJSONParser = function() {
-  this.parser = new parser.instance();
-  this.parser.addListener('object', this.processJSONObject(this))
-};
+// UTILITY METHODS
 
+// Creates a callback for the object Event of the JSON Parser.
+//
+// twit - an instance of this TwitterNode.
+//
+// Returns a function to be passed to the addListener call on the parser.
 TwitterNode.prototype.processJSONObject = function(twit) {
   return function(tweet) {
     if(tweet.limit) {
@@ -97,23 +137,46 @@ TwitterNode.prototype.processJSONObject = function(twit) {
   }
 }
 
+// Passes the received data to the streaming JSON parser.
+//
+// chunk - String data received from the HTTP stream.
+//
+// Returns nothing.
 TwitterNode.prototype.receive = function(chunk) {
   this.parser.receive(chunk);
 };
 
-// override this to pass in your own client if needed.
+// Creates the HTTP client object for the stream connection.  Override this
+// to pass in your own client if needed.
+//
+// port - Integer port number to connect to.
+// host - String host name to connect to.
+//
+// returns Http Client instance.
 TwitterNode.prototype.createClient = function(port, host) {
   return http.createClient(this.port, this.host)
 };
 
+// Base64 encodes the given username and password.
+//
+// user - String Twitter screen name or email.
+// pass - String password.
+//
+// Returns a Basic Auth header fit for HTTP.
 TwitterNode.prototype.basicAuth = function(user, pass) {
   return "Basic " + b64.encode(user + ":" + pass)
 };
 
+// Builds the URL for the streaming request.
+//
+// Returns a String absolute URL.
 TwitterNode.prototype.requestUrl = function() {
   return this.path + this.action + ".json" + this.buildParams()
 };
 
+// Builds the GET params for the streaming request.
+//
+// Returns URI encoded string: "?track=LOST"
 TwitterNode.prototype.buildParams = function() {
   var options = {}
   process.mixin(options, this.params)