module: document important methods

Signed-off-by: Fedor Indutny <fedor@indutny.com>

lib/module.js

@@ -265,6 +265,13 @@ Module._resolveLookupPaths = function(request, parent) {
 };
 
 
+// Check the cache for the requested file.
+// 1. If a module already exists in the cache: return its exports object.
+// 2. If the module is native: call `NativeModule.require()` with the
+//    filename and return the result.
+// 3. Otherwise, create a new module for the file and save it to the cache.
+//    Then have it load  the file contents before returning its exports
+//    object.
 Module._load = function(request, parent, isMain) {
   if (parent) {
     debug('Module._load REQUEST  ' + (request) + ' parent: ' + parent.id);
@@ -336,6 +343,7 @@ Module._resolveFilename = function(request, parent) {
 };
 
 
+// Given a file name, pass it to the proper extension handler.
 Module.prototype.load = function(filename) {
   debug('load ' + JSON.stringify(filename) +
         ' for module ' + JSON.stringify(this.id));
@@ -351,6 +359,8 @@ Module.prototype.load = function(filename) {
 };
 
 
+// Loads a module at the given file path. Returns that module's
+// `exports` property.
 Module.prototype.require = function(path) {
   assert(util.isString(path), 'path must be a string');
   assert(path, 'missing path');
@@ -363,7 +373,10 @@ Module.prototype.require = function(path) {
 var resolvedArgv;
 
 
-// Returns exception if any
+// Run the file contents in the correct scope or sandbox. Expose
+// the correct helper variables (require, module, exports) to
+// the file.
+// Returns exception, if any.
 Module.prototype._compile = function(content, filename) {
   var self = this;
   // remove shebang