diff --git a/lib/cache.js b/lib/cache.js index ed1d23d6..862fd720 100644 --- a/lib/cache.js +++ b/lib/cache.js @@ -16,10 +16,19 @@ class Cache { this.cacheFolder = path.join(config.cache, 'cache'); } + /** + * Fetch stats from the cache folder. + * @returns {Promise} 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} + */ getPage(page) { let preferredPlatform = platform.getPreferredPlatformFolder(this.config); const preferredLanguage = process.env.LANG || 'en'; @@ -36,10 +45,18 @@ class Cache { }); } + /** + * Clean the cache folder. + * @returns {Promise} A promise when the remove is completed. + */ clear() { return fs.remove(this.cacheFolder); } + /** + * Update the cache folder and returns the English entries. + * @returns {Promise} A promise with the index. + */ update() { // Temporary folder path: /tmp/tldr/{randomName} const tempFolder = path.join(os.tmpdir(), 'tldr', utils.uniqueId()); diff --git a/lib/index.js b/lib/index.js index d116b5b5..7f5e6f93 100644 --- a/lib/index.js +++ b/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} 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} 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} 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,8 +170,12 @@ 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} The index entries. + */ function getShortIndex() { if (shortIndex) { return Promise.resolve(shortIndex); @@ -159,9 +183,13 @@ function getShortIndex() { 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} The index entries. + */ function readShortPagesIndex() { return fs.readJson(shortIndexFile) .then((idx) => { diff --git a/lib/remote.js b/lib/remote.js index 51329b56..4b315c86 100644 --- a/lib/remote.js +++ b/lib/remote.js @@ -4,7 +4,11 @@ const unzip = require('node-unzip-2'); 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} A promise when the operation is completed. + */ exports.download = (path) => { const url = config.get().repository; diff --git a/lib/tldr.js b/lib/tldr.js index 3c0ffcb2..2397bcff 100644 --- a/lib/tldr.js +++ b/lib/tldr.js @@ -21,6 +21,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} A promise when the operation is completed. + */ list(singleColumn) { let os = platform.getPreferredPlatformFolder(this.config); return index.commandsFor(os) @@ -29,6 +34,11 @@ class Tldr { }); } + /** + * Print all pages in the cache. + * @param singleColumn {boolean} A boolean to print one command per line. + * @returns {Promise} A promise when the operation is completed. + */ listAll(singleColumn) { return index.commands() .then((commands) => { @@ -36,10 +46,21 @@ class Tldr { }); } + /** + * Print a command page. + * @param commands {string[]} A given command to be printed. + * @param options {object} The options for the render. + * @returns {Promise} 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} A promise when the operation is completed. + */ random(options) { let os = platform.getPreferredPlatformFolder(this.config); return index.commandsFor(os) @@ -56,6 +77,10 @@ class Tldr { }); } + /** + * Print a random page. + * @returns {Promise} A promise when the opration is completed. + */ randomExample() { let os = platform.getPreferredPlatformFolder(this.config); return index.commandsFor(os) @@ -72,6 +97,11 @@ class Tldr { }); } + /** + * Print a markdown file. + * @param file {string} The path to the file. + * @returns {Promise} A promise when the operation is completed. + */ render(file) { return fs.readFile(file, 'utf8') .then((content) => { @@ -82,24 +112,41 @@ class Tldr { }); } + /** + * Clear the cache folder. + * @returns {Promise} A promise when the cache is deleted. + */ clearCache() { return this.cache.clear().then(() => { console.log('Done'); }); } + /** + * Update the cache. + * @returns {Promise} A promise with the index. + */ updateCache() { return spinningPromise('Updating...', () => { return this.cache.update(); }); } + /** + * Update the index. + * @returns {Promise} 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} A promise when the operation is completed. + */ search(keywords) { return search.getResults(keywords.join(' ')) .then((results) => { @@ -108,6 +155,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} A promise when the operation is completed. + */ printPages(pages, singleColumn) { if (pages.length === 0) { throw new EmptyCacheError(); @@ -120,7 +173,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} 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) => { @@ -153,6 +214,10 @@ class Tldr { }); } + /** + * Print a warning message if the cache is 30 days old. + * @returns {Promise} A promise when the operation is completed. + */ checkStale() { return this.cache.lastUpdated() .then((stats) => { @@ -162,7 +227,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); } @@ -177,6 +247,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);