[doc minor] Added more code documentation. Small updates to some var names and to README.md

Author: indexzero

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Charlie Robbins
+Copyright (c) 2010 Charlie Robbins
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -36,6 +36,13 @@ There also seemed to be a log of libraries out there that were coupling their im
 2. [socket.io](http://socket.io)
 3. [node-rlog](https://github.com/jbrisbin/node-rlog)
 
+## Road Map
+1. Make levels configurable for user preference (npm-style, syslog-style, etc)
+2. Create API for reading from logs across all transports.  
+3. Add more transports and make existing transports more robust:
+  a. Riak
+  b. CouchDB
+  c. Redis
 
 ## Run Tests
 All of the winston tests are written in [vows][1], and cover all of the use cases described above. You will need to add valid credentials for the various transports included to test/test-config.json before running tests:

lib/winston.js

@@ -9,6 +9,10 @@
 require.paths.unshift(require('path').join(__dirname));
 
 var winston = exports;
+
+//
+// Include transports defined by default by winston
+//
 winston.transports = require('winston/transports');
 
 //
@@ -45,6 +49,10 @@ Object.keys(defaultLogger.levels).forEach(function (level) {
   };
 });
 
+//
+// function defaultTransports ()
+//   returns the transports set on the default winston logger 
+//
 winston.defaultTransports = function () {
   return defaultLogger.transports;
 };

lib/winston/logger.js

@@ -1,4 +1,11 @@
-
+/*
+ * logger.js: Core logger object used by winston.
+ *
+ * (C) 2010 Charlie Robbins
+ * MIT LICENCE
+ *
+ */
+ 
 require.paths.unshift(require('path').join(__dirname, '..'));
 
 var util = require('util'),
@@ -40,6 +47,7 @@ var Logger = exports.Logger = function (options) {
 
 util.inherits(Logger, events.EventEmitter);
 
+// TODO: Make levels configurable
 var levels = Logger.prototype.levels = {
   silly: 0, 
   verbose: 1, 
@@ -51,7 +59,7 @@ var levels = Logger.prototype.levels = {
 
 //
 // Define prototype methods for each log level 
-// i.e. logger.log('info', msg) <=> logger.info(msg)
+// e.g. logger.log('info', msg) <=> logger.info(msg)
 //
 Object.keys(levels).forEach(function (level) {
   Logger.prototype[level] = function (msg, meta, callback) {
@@ -100,6 +108,10 @@ Logger.prototype.log = function (level, msg) {
   };
 };
 
+//
+// function add (transport, [options])
+//   Adds a transport of the specified type to this instance.
+//
 Logger.prototype.add = function (transport, options) {
   var name = winston.findTransport(transport);
 
@@ -110,6 +122,10 @@ Logger.prototype.add = function (transport, options) {
   return this;
 };
 
+//
+// function remove (transport) 
+//   Removes a transport of the specified type from this instance.
+//
 Logger.prototype.remove = function (transport) {
   var name = winston.findTransport(transport);
   if (!this.transports[name]) throw new Error('Transport ' + name + ' not attached to this instance');
@@ -120,15 +136,21 @@ Logger.prototype.remove = function (transport) {
   return this;
 };
 
+//
+// function profile (msg, [callback])
+//   Tracks the time inbetween subsequent calls to this method
+//   with the same [msg] parameter. The second call to this method
+//   will log the difference in milliseconds along with the message.
+//
 Logger.prototype.profile = function (name, callback) {
   var now = Date.now(), then;
 
-  if (this.profilers[name]) {
-    then = this.profilers[name];
-    delete this.profilers[name];
-    return this.info(now - then + 'ms - ' + name, callback);
+  if (this.profilers[msg]) {
+    then = this.profilers[msg];
+    delete this.profilers[msg];
+    return this.info(now - then + 'ms - ' + msg, callback);
   }
   else {
-    this.profilers[name] = now;
+    this.profilers[msg] = now;
   }
 };

lib/winston/transports/console.js

@@ -10,6 +10,10 @@ var util = require('util'),
     colors = require('colors'),
     log = require('./../utils').log;
 
+//
+// function Console (options)
+//   Constructor for the Console transport object.
+//
 var Console = exports.Console = function (options) {
   options = options || {};
 
@@ -19,6 +23,10 @@ var Console = exports.Console = function (options) {
   this.colorize = options.colorize;
 };
 
+//
+// function log (level, msg, [meta], callback)
+//   Core logging method exposed to Winston. Metadata is optional.
+//
 Console.prototype.log = function (level, msg, meta, callback) {
   if (!this.silent) {
     var output = log(level, msg, meta);

lib/winston/transports/file.js

@@ -11,6 +11,10 @@ var util = require('util'),
     colors = require('colors'),
     log = require('./../utils').log;
 
+//
+// function File (options)
+//   Constructor for the File transport object.
+//
 var File = exports.File = function (options) {
   options = options || {}
 
@@ -24,6 +28,10 @@ var File = exports.File = function (options) {
   this.colorize = options.colorize;
 };
 
+//
+// function log (level, msg, [meta], callback)
+//   Core logging method exposed to Winston. Metadata is optional.
+//
 File.prototype.log = function (level, msg, meta, callback) {
   if (!this.silent) {
     var output = log(level, msg, meta) + '\n';

lib/winston/transports/loggly.js

@@ -9,6 +9,10 @@
 var loggly = require('loggly'),
     utils = require('./../utils'); 
 
+//
+// function Loggly (options)
+//   Constructor for the Loggly transport object.
+//
 var Loggly = exports.Loggly = function (options) {
   options = options || {};
   if (!options.auth)       throw new Error('Loggly authentication is required');
@@ -39,6 +43,10 @@ var Loggly = exports.Loggly = function (options) {
   }
 };
 
+//
+// function log (level, msg, [meta], callback)
+//   Core logging method exposed to Winston. Metadata is optional.
+//
 Loggly.prototype.log = function (level, msg, meta, callback) {
   var message = utils.clone(meta);
   message.level = level;

lib/winston/transports/riak.js

@@ -9,7 +9,11 @@
 
 var riakjs = require('riak-js'),
     utils = require('./../utils');
- 
+
+//
+// function Riak (options)
+//   Constructor for the Riak transport object.
+//
 var Riak = exports.Riak = function (options) {
   options = options || {};
   this.client = riakjs.getClient(options);
@@ -19,6 +23,10 @@ var Riak = exports.Riak = function (options) {
   this.bucketName = options.bucketName || Date.now;
 };
 
+//
+// function log (level, msg, [meta], callback)
+//   Core logging method exposed to Winston. Metadata is optional.
+//
 Riak.prototype.log = function (level, msg, meta, callback) {
   var metac = utils.clone(meta);
   metac.level = level;

lib/winston/utils/index.js

@@ -45,7 +45,8 @@ var timestamp = exports.timestamp = function () {
 }
 
 //
-// Generic logging function for returning timestamped strings
+// function log (level, msg, meta)
+//   Generic logging function for returning timestamped strings
 //
 var log = exports.log = function (level, msg, meta) {
   var output = timestamp() + ' - ' + level + ': ' + msg;

usage.js

@@ -24,9 +24,7 @@ winston.add('loggly', {
 });
 
 // Remove console (set by default)
-winston.remove('console');
-
-winston.load('config-file.json');
+winston.remove(winston.transports.Console);
 
 //
 // Remark: These statements are equivalent
@@ -42,17 +40,18 @@ winston.info('some message', { metadata: 'hi'});
 
 var options = {
   emitErrs: false,
-  transports: {
-    'riak': winston.default, 
-    'loggly': {
+  transports: [
+    new (winston.transports.Riak)(),
+    new (winston.transports.Loggly)({
       subdomain: 'winston',
       inputToken: 'really-long-thing-you-got-from-loggly',
       auth: {
         username: 'user',
         password: 'pass'
       }
-    }
-  }
+    })
+  ]
 }
+
 var logger = new (winston.Logger)(options);
 logger.log('info', { message: 'some message' });