[DOCS] documents some files in the 'utils' folder

Author: carlos3g

src/utils/Parse.js

@@ -1,25 +1,56 @@
+/**
+ * Extract useful data from a given string (usually the content of a message).
+ * @example
+ * const messageContent = '!command --arg1 --kwarg=1 any text here'
+ * const data = new Parse(messageContent)
+ * data.command // command
+ * data.args // ['arg1']
+ * data.kwargs // { kwarg: 1 }
+ * data.text // 'any text here'
+ * @param {string} text - Text to be parsed.
+ */
 class Parse {
   constructor(text) {
+    /** The original text. */
     this.rawText = text.trim();
+
+    /**
+     * A collection of regular expressions used in the extraction of data from the `this.rawText`.
+     * @property {string} REGEXP.command - Regular expression for commands. Ex: !command
+     * @property {string[]} REGEXP.args - Regular expression for args. Ex: --arg1
+     * @property {object} REGEXP.kwargs - Regular expression for kwargs. Ex: --kwarg=1
+     */
     this.REGEXP = {
       command: /^!([^\s]+)/,
       args: /--([\S]+)(?=\s|$)/g,
       kwargs: /--([a-zA-Z0-9_-]+)="?([a-z0-9\.]+)"?/g, // eslint-disable-line
     };
   }
 
+  /**
+   * Gets the command extracted from the `this.rawText`.
+   * @returns {string}
+   */
   get command() {
     const matches = this.rawText.match(this.REGEXP.command);
     return matches ? matches[1] : '';
   }
 
+  /**
+   * Gets the args extracted from `this.rawText`.
+   * @returns {string[]}
+   */
   get args() {
     const matchesIter = this.rawText.matchAll(this.REGEXP.args);
     const matchesArray = [...matchesIter];
     const matches = matchesArray.map((elem) => elem[1]);
     return matches;
   }
 
+  /**
+   * Gets the kwargs extracted from `this.rawText`.
+   * @returns {object}
+   */
   get kwargs() {
     const obj = {};
     const matchesIter = this.rawText.matchAll(this.REGEXP.kwargs);
@@ -32,6 +63,10 @@ class Parse {
     return obj;
   }
 
+  /**
+   * Gets the text extracted from `this.rawText`.
+   * @returns {string}
+   */
   get text() {
     return this.rawText
       .replace(this.REGEXP.command, '')

src/utils/chattools.js

@@ -1,18 +1,20 @@
 /**
- * Get serialized number
- * @param {Array<Object>} idList - An array containing objects about user identification.
- * @return {Array<String>} - Contains serialized phone numbers
+ * Get serialized phone number from a given array of users.
+ * @param {Contact[]} users - Whatsapp users.
+ * @see https://docs.wwebjs.dev/Contact.html
+ * @returns {string[]} - Serialized phone numbers.
  */
-function getSerialList(idList) {
+function getSerialList(users) {
   // eslint-disable-next-line no-underscore-dangle
-  const serialList = idList.map((id) => id.id._serialized);
+  const serialList = users.map((u) => u.id._serialized);
   return serialList;
 }
 
 /**
- * Get serialized number of all members in group
- * @param {Object} chat - Object that represents the current chat
- * @return {Array<String>} - Contains serialized phone numbers of all members
+ * Get serialized phone number of all members from a given group.
+ * @param {Chat} chat - A whatsapp chat.
+ * @see https://docs.wwebjs.dev/Chat.html
+ * @returns {string[]} - Serialized phone numbers of all members.
  */
 async function getMembersList(chat) {
   const members = await chat.participants;
@@ -21,9 +23,10 @@ async function getMembersList(chat) {
 }
 
 /**
- * Get serialized number of all administrators in group
- * @param {Object} chat - Object that represents the current chat
- * @return {Array<String>} - Contains serialized phone numbers of all administrators
+ * Get serialized phone number of all administrators from a given group.
+ * @param {Chat} chat - A whatsapp chat.
+ * @see https://docs.wwebjs.dev/Chat.html
+ * @returns {string[]} - Serialized phone numbers of all administrators.
  */
 async function getAdmsList(chat) {
   const members = await chat.participants;
@@ -33,9 +36,10 @@ async function getAdmsList(chat) {
 }
 
 /**
- * Check if a message if from an adm
- * @param {Object} message - Object that represents the current message
- * @return {Boolean}
+ * Checks if a message is from an ADM.
+ * @param {Message} message - Message to check if is from an ADM.
+ * @see https://docs.wwebjs.dev/Message.html
+ * @returns {boolean}
  */
 async function isAdm(message) {
   const chat = await message.getChat();
@@ -44,12 +48,17 @@ async function isAdm(message) {
   return admList.includes(author);
 }
 
-function userID(targetNumber) {
-  if (typeof targetNumber !== 'string') {
+/**
+ * Get a whatsapp user id for a given phone number.
+ * @param {string} phoneNumber
+ * @returns {string}
+ */
+function userID(phoneNumber) {
+  if (typeof phoneNumber !== 'string') {
     throw new Error('you must pass the number as a string');
   }
 
-  const target = targetNumber.replace(/\D/g, '');
+  const target = phoneNumber.replace(/\D/g, '');
   const regexp = /\d+/;
   const matches = target.match(regexp);
   const pattern = matches[0];

src/utils/search.js

@@ -1,6 +1,13 @@
 const googleIt = require('google-it');
 
-async function google(query, target = '', limit = null) {
+/**
+ * Searchs for a given string in google.
+ * @param {string} query Text that must be searched.
+ * @param {string} [target=''] Target site to search in.
+ * @param {number} [limit=0] Max number of results that must be returned.
+ * @returns {object[]} Array of results found.
+ */
+async function google(query, target = '', limit = 0) {
   const result = await googleIt({
     query,
     includeSites: target,

src/utils/time.js

@@ -1,12 +1,25 @@
+/**
+ * Suspends (waits) execution of the current thread for a given number of seconds.
+ * @param {number} seconds
+ * @returns {Promise}
+ */
 function sleep(seconds) {
   return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
 }
 
-function timer(sec = 0, min = 0, hour = 0, day = 0) {
-  const secsInMS = sec * 1000;
-  const minsInMS = min * 60 * 1000;
-  const hoursInMS = hour * 60 * 60 * 1000;
-  const daysInMS = day * 24 * 60 * 60 * 1000;
+/**
+ * Converts a given set of seconds, minutes, hours and days in miliseconds.
+ * @param {number} [secs=0]
+ * @param {number} [mins=0]
+ * @param {number} [hours=0]
+ * @param {number} [days=0]
+ * @returns {number} Total time in miliseconds.
+ */
+function timer(secs = 0, mins = 0, hours = 0, days = 0) {
+  const secsInMS = secs * 1000;
+  const minsInMS = mins * 60 * 1000;
+  const hoursInMS = hours * 60 * 60 * 1000;
+  const daysInMS = days * 24 * 60 * 60 * 1000;
   const timeInMS = secsInMS + minsInMS + hoursInMS + daysInMS;
   return timeInMS;
 }