add jsdocs to tldr and cache

Author: navarroaxel

lib/cache.js

@@ -14,10 +14,19 @@ class Cache {
     this.cacheFolder = path.join(config.cache, 'cache');
   }
 
+  /**
+   * Fetch stats from the cache folder.
+   * @returns {Promise<any>} A promise with the stats of the cache folder.
+   */
   lastUpdated() {
     return fs.stat(this.cacheFolder);
   }
 
+  /**
+   * Fetch a page from cache using preferred language and preferred platform.
+   * @param page {} A
+   * @returns {Promise<unknown>}
+   */
   getPage(page) {
     let preferredPlatform = platforms.getPreferredPlatformFolder(this.config);
     const preferredLanguage = process.env.LANG || 'en';
@@ -34,10 +43,18 @@ class Cache {
       });
   }
 
+  /**
+   * Clean the cache folder.
+   * @returns {Promise<any>} A promise when the remove is completed.
+   */
   clear() {
     return fs.remove(this.cacheFolder);
   }
 
+  /**
+   * Update the cache folder and returns the English entries.
+   * @returns {Promise<any>} A promise with the index.
+   */
   update() {
     // Temporary folder path: /tmp/tldr/{randomName}
     const tempFolder = path.join(os.tmpdir(), 'tldr', utils.uniqueId());

lib/index.js

@@ -91,17 +91,24 @@ function hasLang(targets, preferredLanguage) {
   });
 }
 
-// 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.
+/**
+ * Check if a page is in the index.
+ * @returns {boolean} A boolean that indicates if the page is present.
+ */
 function hasPage(page) {
+  // 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.
   if (!shortIndex) {
     return false;
   }
   return page in shortIndex;
 }
 
-// Return all commands available in the local cache.
+/**
+ * Return all commands available in the local cache.
+ * @returns {Promise<string[]>} A promise with the commands from cache.
+ */
 function commands() {
   return getShortIndex().then((idx) => {
     return Object.keys(idx).sort();
@@ -110,6 +117,13 @@ function commands() {
 
 // Return all commands for a given platform.
 // P.S. - The platform 'common' is always included.
+/**
+ * Return all commands for a given platform.
+ *
+ * The 'common' platform is always included.
+ * @param platform {string} The platform.
+ * @returns {Promise<string[]>} A promise with the commands for a given platform.
+ */
 function commandsFor(platform) {
   return getShortIndex()
     .then((idx) => {
@@ -124,7 +138,11 @@ function commandsFor(platform) {
     });
 }
 
-// Delete the index file.
+/**
+ * Delete the index file.
+ *
+ * @returns {Promise<any>} A promise when the remove is completed.
+ */
 function clearPagesIndex() {
   return fs.unlink(shortIndexFile)
     .then(() => {
@@ -139,7 +157,9 @@ function clearPagesIndex() {
     });
 }
 
-// Set the shortIndex variable to null.
+/**
+ * Set the shortIndex variable to null.
+ */
 function clearRuntimeIndex() {
   shortIndex = null;
 }
@@ -150,18 +170,26 @@ function rebuildPagesIndex() {
   });
 }
 
-// If the variable is not set, read the file and set it.
-// Else, just return the variable.
+/**
+ * Return the index.
+ *
+ * If the index is not loaded, read the file and load it.
+ * @returns {Promise<any>} The index entries.
+ */
 function getShortIndex() {
   if (shortIndex) {
     return Promise.resolve(shortIndex);
   }
   return readShortPagesIndex();
 }
 
-// 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.
+/**
+ * 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.
+ * @returns {Promise<any>} The index entries.
+ */
 function readShortPagesIndex() {
   return fs.readJson(shortIndexFile)
     .then((idx) => {

lib/remote.js

@@ -6,7 +6,11 @@ const unzip = require('adm-zip');
 const config = require('./config');
 const axios = require('axios');
 
-// Downloads the zip file from github and extracts it to folder
+/**
+ * Download the zip file from GitHub and extract it to folder.
+ * @param path {string} Path to destination folder.
+ * @returns {Promise<void>} A promise when the operation is completed.
+ */
 exports.download = (loc, lang) => {
   // If the lang is english then keep the url simple, otherwise add language.
   const suffix = (lang === 'en' ? '' : '.' + lang);
@@ -26,7 +30,7 @@ exports.download = (loc, lang) => {
 
       const writer = fs.createWriteStream(fileName);
       response.data.pipe(writer);
-    
+
       writer.on('finish', () => {
         writer.end();
         const zip = new unzip(fileName);
@@ -41,4 +45,4 @@ exports.download = (loc, lang) => {
   }).catch((err) => {
     return Promise.reject(err);
   });
-};
+};

lib/tldr.js

@@ -19,6 +19,11 @@ class Tldr {
     this.cache = new Cache(this.config);
   }
 
+  /**
+   * Print pages for a given platform..
+   * @param singleColumn {boolean} A boolean to print one command per line.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   list(singleColumn) {
     let platform = platforms.getPreferredPlatformFolder(this.config);
     return index.commandsFor(platform)
@@ -27,17 +32,33 @@ class Tldr {
       });
   }
 
+  /**
+   * Print all pages in the cache.
+   * @param singleColumn {boolean} A boolean to print one command per line.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   listAll(singleColumn) {
     return index.commands()
       .then((commands) => {
         return this.printPages(commands, singleColumn);
       });
   }
 
+  /**
+   * Print a command page.
+   * @param commands {string[]} A given command to be printed.
+   * @param options {object} The options for the render.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   get(commands, options) {
     return this.printBestPage(commands.join('-'), options);
   }
 
+  /**
+   * Print a random page for the current platform.
+   * @param options {object} The options for the render.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   random(options) {
     let platform = platforms.getPreferredPlatformFolder(this.config);
     return index.commandsFor(platform)
@@ -54,6 +75,10 @@ class Tldr {
       });
   }
 
+  /**
+   * Print a random page.
+   * @returns {Promise<void>} A promise when the opration is completed.
+   */
   randomExample() {
     let platform = platforms.getPreferredPlatformFolder(this.config);
     return index.commandsFor(platform)
@@ -70,6 +95,11 @@ class Tldr {
       });
   }
 
+  /**
+   * Print a markdown file.
+   * @param file {string} The path to the file.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   render(file) {
     if (typeof file !== 'string') {
       throw new MissingRenderPathError();
@@ -83,24 +113,41 @@ class Tldr {
       });
   }
 
+  /**
+   * Clear the cache folder.
+   * @returns {Promise<void>} A promise when the cache is deleted.
+   */
   clearCache() {
     return this.cache.clear().then(() => {
       console.log('Done');
     });
   }
 
+  /**
+   * Update the cache.
+   * @returns {Promise<any>} A promise with the index.
+   */
   updateCache() {
     return spinningPromise('Updating...', () => {
       return this.cache.update();
     });
   }
 
+  /**
+   * Update the index.
+   * @returns {Promise<any>} A promise with the index.
+   */
   updateIndex() {
     return spinningPromise('Creating index...', () => {
       return search.createIndex();
     });
   }
 
+  /**
+   * Search some keywords in the index and print the results.
+   * @param keywords {string[]} The given keywords.
+   * @returns {Promise<any>} A promise when the operation is completed.
+   */
   search(keywords) {
     return search.getResults(keywords.join(' '))
       .then((results) => {
@@ -109,6 +156,12 @@ class Tldr {
       });
   }
 
+  /**
+   * Print all pages.
+   * @param pages {string[]} A list of pages to be printed.
+   * @param singleColumn {boolean} A boolean to print one command per line.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   printPages(pages, singleColumn) {
     if (pages.length === 0) {
       throw new EmptyCacheError();
@@ -121,7 +174,15 @@ class Tldr {
       });
   }
 
-  printBestPage(command, options={}) {
+  /**
+   * Print a page from the cache.
+   *
+   * If the page is not present, the cache is updated.
+   * @param command {string} The given command to be printed.
+   * @param options {object} The options for the render.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
+  printBestPage(command, options= {}) {
     // Trying to get the page from cache first
     return this.cache.getPage(command)
       .then((content) => {
@@ -157,6 +218,10 @@ class Tldr {
       });
   }
 
+  /**
+   * Print a warning message if the cache is 30 days old.
+   * @returns {Promise<void>} A promise when the operation is completed.
+   */
   checkStale() {
     return this.cache.lastUpdated()
       .then((stats) => {
@@ -166,7 +231,12 @@ class Tldr {
       });
   }
 
-  renderContent(content, options={}) {
+  /**
+   * Print the page content.
+   * @param content {string} The content of a page.
+   * @param options {object<{markdown: boolean, randomExample: boolean}>} The options for the render.
+   */
+  renderContent(content, options= {}) {
     if (options.markdown) {
       return console.log(content);
     }
@@ -181,6 +251,12 @@ class Tldr {
   }
 }
 
+/**
+ * Display a spinner while a task is running.
+ * @param text {string} The text of the spinner.
+ * @param factory {Function} A task to be run.
+ * @returns {Promise} A promise with the result of the task.
+ */
 function spinningPromise(text, factory) {
   const spinner = ora();
   spinner.start(text);