Fixing a bug in Email.prototype.resolve and adding comments, ref #1

lib/Email.js

@@ -7,6 +7,10 @@ var getEngine = require('./util/getEngine');
 var getTransport = require('./util/getTransport');
 var isFile = require('./util/isFile');
 
+/*
+Email constructor. Requires a template path to be provided, and a valid engine
+must be specified in the options. See Readme.md for explanation
+*/
 function Email (template, options) {
 	debug('email %s', template);
 
@@ -44,6 +48,10 @@ function Email (template, options) {
 	}
 }
 
+/*
+Renders the template without sending an email. Options are passed to the
+template as local variables.
+*/
 Email.prototype.render = function (options, callback) {
 	if (typeof options === 'function') {
 		callback = options;
@@ -62,14 +70,30 @@ Email.prototype.render = function (options, callback) {
 	});
 };
 
+/*
+Resolves the path for a template, and ensures it points to a file
+*/
 Email.prototype.resolve = function (name) {
+	// resolve the name with the root option
 	var loc = path.resolve(this.root, name);
+	// pull the directory part out of the resolved path
 	var dir = path.dirname(loc);
+	// put the filename part out of the resolved path, without the extension
+	// since the extension may or may not be provided in name, we explicitly
+	// put it back in the next step
 	var file = path.basename(loc, this.ext);
-	var filepath = path.join(dir, file);
+	// join the directory, filename and extension to get the full path
+	var filepath = path.join(dir, file + this.ext);
+	// if the file exists, return the resolved path, otherwise undefined
 	return isFile(filepath) ? filepath : undefined;
 };
 
+/*
+Sends the email. Will render the template first
+
+Takes renderOptions (i.e. local variables for the template) and sendOptions
+(passed to the transport) - see Readme.md for explanation
+*/
 Email.prototype.send = function (renderOptions, sendOptions, callback) {
 	if (!this.transport) {
 		return callback(new Error('Transport must be set to use Email.send()'));
@@ -80,6 +104,10 @@ Email.prototype.send = function (renderOptions, sendOptions, callback) {
 	});
 };
 
+/*
+Shorthand method to create and send an email in a single call without
+creating a new Email() instance. Requires all options objects to be provided
+*/
 Email.send = function (template, emailOptions, renderOptions, sendOptions, callback) {
 	return new Email(template, emailOptions).send(renderOptions, sendOptions, callback);
 };