add jsdocs to tldr and cache #355

navarroaxel · 2021-05-25T03:50:59Z

Description

Please explain the changes you made here.

Checklist

Please review this checklist before submitting a pull request.

Code compiles correctly
Created tests, if possible
All tests passing (npm run test:all)
Extended the README / documentation, if necessary

blueskyson

Wow, I wonder why comment enhancements are left so long unmerged.

agnivade · 2023-07-17T04:06:51Z

lib/cache.js

+ /**
+ * Fetch a page from cache using preferred language and preferred platform.
+ * @param page {} A
+ * @returns {Promise<unknown>}


What is the difference between Promise<any> and Promise<unknown> ?

agnivade · 2023-07-17T04:07:32Z

lib/index.js

 // Return all commands for a given platform.
 // P.S. - The platform 'common' is always included.


Should we remove this then? Seems repeated.

agnivade · 2023-07-17T04:08:37Z

lib/tldr.js

@@ -21,6 +21,11 @@ class Tldr {
 this.cache = new Cache(this.config);
 }

+ /**
+ * Print pages for a given platform..


Multiple periods at the end of the sentence.

agnivade · 2023-07-17T04:09:36Z

lib/tldr.js

 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.


"A given command" is incorrect when we are passing an array. Let's change this to plural.

agnivade · 2023-07-17T04:10:49Z

lib/tldr.js

 clearCache() {
 return this.cache.clear().then(() => {
 console.log('Done');
 });
 }

+ /**
+ * Update the cache.
+ * @returns {Promise<any>} A promise with the index.


Should this be "A promise with the cache"?

vitorhcl

LGTM after we address the left concerns.

However, we can resolve just some of them and merge it, this PR adds documentation for quite a lot of functions. It's better to have a not ideal documentation than almost no documentation.

vitorhcl · 2024-03-16T19:05:45Z

lib/tldr.js

@@ -21,6 +21,11 @@ class Tldr {
 this.cache = new Cache(this.config);
 }

+ /**
+ * Print pages for a given platform..


Suggested change

* Print pages for a given platform..

* Print pages for a given platform.

vitorhcl · 2024-03-16T20:12:14Z

lib/tldr.js

 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.


Suggested change

* @param commands {string[]} A given command to be printed.

* @param commands {string[]} Given commands to be printed.

vitorhcl · 2024-03-16T20:27:00Z

lib/index.js

+ * Return all commands for a given platform.
+ *
+ * The 'common' platform is always included.
+ * @param platform {string} The platform.


Suggested change

* @param platform {string} The platform.

* @param platform {string} The desired platform.

vitorhcl · 2024-03-16T20:31:49Z

lib/tldr.js

@@ -56,6 +77,10 @@ class Tldr {
 });
 }

+ /**
+ * Print a random page.


Suggested change

* Print a random page.

* Print a random page example.

vitorhcl · 2024-03-16T20:40:32Z

lib/cache.js

@@ -16,10 +16,19 @@ class Cache {
 this.cacheFolder = path.join(config.cache, 'cache');
 }

+ /**
+ * Fetch stats from the cache folder.


Suggested change

* Fetch stats from the cache folder.

* Fetch stats from the cache folder for getting its last modified time (mtime).

vitorhcl · 2024-03-16T22:04:53Z

lib/index.js

-// 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.


Suggested change

* @returns {boolean} A boolean that indicates if the page is present.

* @returns {boolean} The presence of the page in the index.

vitorhcl · 2024-03-16T22:10:58Z

lib/cache.js

 clear() {
 return fs.remove(this.cacheFolder);
 }

+ /**
+ * Update the cache folder and returns the English entries.


Suggested change

* Update the cache folder and returns the English entries.

* Update the cache folder using a temporary directory, update the index and return it.

vitorhcl · 2024-03-16T22:12:06Z

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.


Suggested change

* @param singleColumn {boolean} A boolean to print one command per line.

* @param singleColumn {boolean} Print one command per line.

vitorhcl · 2024-03-17T01:23:08Z

lib/tldr.js

@@ -29,17 +34,33 @@ class Tldr {
 });
 }

+ /**
+ * Print all pages in the cache.


Suggested change

* Print all pages in the cache.

* Print the name of all pages in the index.

vitorhcl · 2024-03-17T01:23:49Z

lib/tldr.js

@@ -108,6 +155,12 @@ class Tldr {
 });
 }

+ /**
+ * Print all pages.


Suggested change

* Print all pages.

* Print the name of all pages.

vitorhcl

#355 (comment):

What is the difference between Promise<any> and Promise<unknown> ?

See https://stackoverflow.com/questions/51439843/unknown-vs-any. In summary:

More verbosely, unknown is I don't know (yet), thus I have to figure it out, any is I don't care, thus I don't care

I think there are too many anys/unknowns here, but we can change them later if we need.

agnivade

I still see my comments not addressed yet. Feel free to request a review once that's done. Thanks.

vitorhcl · 2024-03-20T21:27:09Z

IMO we can take over this PR, since it was opened 2 years ago with no response since then.

add jsdocs to tldr and cache

7776bb4

blueskyson approved these changes Jul 16, 2023

View reviewed changes

blueskyson requested review from agnivade and MasterOdin July 16, 2023 06:16

kbdharun approved these changes Jul 16, 2023

View reviewed changes

agnivade reviewed Jul 17, 2023

View reviewed changes

kbdharun changed the base branch from master to main October 3, 2023 17:12

vitorhcl approved these changes Mar 17, 2024

View reviewed changes

vitorhcl reviewed Mar 17, 2024

View reviewed changes

vitorhcl requested review from blueskyson and kbdharun March 19, 2024 18:20

kbdharun requested a review from agnivade March 20, 2024 01:45

agnivade reviewed Mar 20, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add jsdocs to tldr and cache #355

add jsdocs to tldr and cache #355

navarroaxel commented May 25, 2021 •

edited

blueskyson left a comment

agnivade Jul 17, 2023

agnivade Jul 17, 2023

agnivade Jul 17, 2023

agnivade Jul 17, 2023

agnivade Jul 17, 2023

vitorhcl left a comment

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 16, 2024

vitorhcl Mar 17, 2024

vitorhcl Mar 17, 2024

vitorhcl left a comment •

edited

agnivade left a comment

vitorhcl commented Mar 20, 2024

		// Return all commands for a given platform.
		// P.S. - The platform 'common' is always included.

	* Print pages for a given platform..
	* Print pages for a given platform.

	* @param commands {string[]} A given command to be printed.
	* @param commands {string[]} Given commands to be printed.

	* @param platform {string} The platform.
	* @param platform {string} The desired platform.

	* Fetch stats from the cache folder.
	* Fetch stats from the cache folder for getting its last modified time (mtime).

	* @returns {boolean} A boolean that indicates if the page is present.
	* @returns {boolean} The presence of the page in the index.

	* Update the cache folder and returns the English entries.
	* Update the cache folder using a temporary directory, update the index and return it.

	* @param singleColumn {boolean} A boolean to print one command per line.
	* @param singleColumn {boolean} Print one command per line.

	* Print all pages in the cache.
	* Print the name of all pages in the index.

add jsdocs to tldr and cache #355

Are you sure you want to change the base?

add jsdocs to tldr and cache #355

Conversation

navarroaxel commented May 25, 2021 • edited

Description

Checklist

blueskyson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vitorhcl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vitorhcl left a comment • edited

Choose a reason for hiding this comment

agnivade left a comment

Choose a reason for hiding this comment

vitorhcl commented Mar 20, 2024

navarroaxel commented May 25, 2021 •

edited

vitorhcl left a comment •

edited