index.js: various documentation fixes

lib/index.js

@@ -13,11 +13,11 @@ const shortIndexFile = path.join(pagesPath, 'shortIndex.json');
 function findPlatform(page, preferredPlatform, done) {
   // Load the index
   getShortIndex((idx) => {
-    // First checking whether page is there or not
+    // First, check whether page is in the index
     if (! (page in idx)) {
       return done(null);
     }
-    // Getting the platforms
+    // Get the platforms
     let platforms = idx[page];
     if (platforms.indexOf(preferredPlatform) >= 0) {
       return done(preferredPlatform);
@@ -28,29 +28,32 @@ function findPlatform(page, preferredPlatform, done) {
   });
 }
 
-// hasPage is always called after index is created, hence just return the variable
-// in memory. There is no need to re-read the index file again.
+// hasPage is always called after the index is created,
+// hence just return the variable in memory.
+// There is no need to re-read the index file again.
 function hasPage(page) {
   if (!shortIndex) {
     return false;
   }
   return page in shortIndex;
 }
 
-// This returns all commands available in the local cache
+// Return all commands available in the local cache.
 function commands(done) {
   getShortIndex((idx) => {
     return done(Object.keys(idx).sort());
   });
 }
 
-// This returns all commands for a given platform.
+// Return all commands for a given platform.
 // P.S. - The platform 'common' is always included.
 function commandsFor(platform, done) {
   getShortIndex((idx) => {
     let commands = Object.keys(idx)
       .filter((cmd) => {
-        /* eslint-disable */ // To allow using -1 to check if it contains in the array
+        // ESLint is disabled for this statement, to allow using -1
+        // to check if a command is contained in the array.
+        /* eslint-disable */
         return idx[cmd].indexOf(platform) !== -1
           || idx[cmd].indexOf('common') !== -1 ;
         /* eslint-enable */
@@ -60,15 +63,15 @@ function commandsFor(platform, done) {
   });
 }
 
-// Delete the index file
+// Delete the index file.
 function clearPagesIndex(done) {
   fs.unlink(shortIndexFile, () => {
     clearRuntimeIndex();
     done();
   });
 }
 
-// Set the variable to null
+// Set the shortIndex variable to null.
 function clearRuntimeIndex() {
   shortIndex = null;
 }
@@ -82,21 +85,21 @@ function rebuildPagesIndex(done) {
 }
 
 // If the variable is not set, read the file and set it.
-// Else, just return the variable
+// Else, just return the variable.
 function getShortIndex(done) {
   if (!shortIndex) {
     return readShortPagesIndex(done);
   }
   return done(shortIndex);
 }
 
-// Reads the index file, and loads it into memory.
-// If the file is not created, create the data structure, write the file, and load
-// it into memory
+// Read the index file, and load it into memory.
+// If the file does not exist, create the data structure, write the file,
+// and load it into memory.
 function readShortPagesIndex(done) {
   fs.readFile(shortIndexFile, 'utf8', (err, idx) => {
-    // file is not present, need to create the index
     if (err) {
+      // File is not present; we need to create the index.
       idx = buildShortPagesIndex();
       if (Object.keys(idx).length > 0) {
         fs.writeFile(shortIndexFile, JSON.stringify(idx), (err) => {
@@ -109,7 +112,9 @@ function readShortPagesIndex(done) {
       } else {
         return done(idx);
       }
-    } else { // Just parse and set shortIndex variable, then return the value
+    } else {
+      // File is present, so just parse and set the shortIndex variable,
+      // then return the value.
       idx = JSON.parse(idx);
       shortIndex = idx;
       return done(idx);