docs(api): add JSDoc annotation for all major accessors and functions…

… in the class Additionally, updates the API.md file
M-Scott-Lassiter · Apr 28, 2022 · a76db95 · a76db95
1 parent 7dddb0b
commit a76db95
Show file tree

Hide file tree

Showing 3 changed files with 185 additions and 34 deletions.
diff --git a/API.md b/API.md
@@ -4,43 +4,131 @@
 
 -   [AlphanumericEncoder][1]
     -   [dictionary][2]
-    -   [dictionary][3]
-        -   [Parameters][4]
+        -   [Parameters][3]
+        -   [Examples][4]
     -   [encode][5]
         -   [Parameters][6]
+        -   [Examples][7]
+    -   [decode][8]
+        -   [Parameters][9]
+        -   [Examples][10]
 
 ## AlphanumericEncoder
 
 A class for encoding and decoding base 10 integers to a custom alphanumeric base representation.
 
 ### dictionary
 
-Returns the current dictionary. Default is the English alphabet in order: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+Set or get the current dictionary.
 
-Returns **[string][7]** The current dictionary in use
-
-### dictionary
+Default is the English alphabet in order: `ABCDEFGHIJKLMNOPQRSTUVWXYZ`
 
 #### Parameters
 
--   `newDictionary` **[string][7]** String of unique characters in order for the new dictionary
+-   `newDictionary` **[string][11]** (If setting) String of unique letters and numbers, in order, for the new dictionary
+
+#### Examples
+
+```javascript
+console.log(AlphanumericEncoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+AlphanumericEncoder.dictionary = 'ABCD'
+console.log(AlphanumericEncoder.dictionary) // 'ABCD'
+
+AlphanumericEncoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated
+```
+
+Returns **[string][11]** (If used as getter) The current dictionary in use
 
 ### encode
 
 Takes any number and converts it into a base (dictionary length) letter combo.
-It converts any numerical entry into a positive integer.
 
 #### Parameters
 
--   `number` **[number][8]** Base 10 number. Must be positive and non-zero. Decimals values are truncated.
+-   `integerToEncode` **[number][12]** Base 10 integer. If passed a non-integer number, decimal values are truncated.
+    Passing zero, negative numbers, or non-numbers will return `undefined`.
+
+#### Examples
+
+```javascript
+const encoder = new AlphanumericEncoder()
+console.log(encoder.encode(5)) // 'E'
+console.log(encoder.encode(48)) // 'AV'
+console.log(encoder.encode(733)) // 'ABE'
+```
+
+```javascript
+const encoder = new AlphanumericEncoder()
+encoder.dictionary = 'ABCD'
+console.log(encoder.encode(5)) // 'AA'
+console.log(encoder.encode(48)) // 'BCD'
+console.log(encoder.encode(733)) // 'BCACA'
+```
+
+```javascript
+const encoder = new AlphanumericEncoder()
+encoder.dictionary = 'DCBA'
+console.log(encoder.encode(5)) // 'DD'
+console.log(encoder.encode(48)) // 'CBA'
+console.log(encoder.encode(733)) // 'CBDBD'
+```
+
+```javascript
+const encoder = new AlphanumericEncoder()
+encoder.dictionary = 'ABC123'
+console.log(encoder.encode(5)) // '2'
+console.log(encoder.encode(48)) // 'AA3'
+console.log(encoder.encode(733)) // 'CBBA'
+```
+
+Returns **[string][11]** Dictionary encoded value
+
+### decode
+
+Takes any string and converts it into a base 10 integer based on the defined dictionary.
+
+#### Parameters
+
+-   `stringToDecode` **[string][11]** If passed a non-integer number, decimal values are truncated.
+    Passing an empty string, `null`, or `undefined` will return `undefined`.
+
+#### Examples
+
+```javascript
+const encoder = new AlphanumericEncoder()
+console.log(encoder.decode('A')) // 1
+console.log(encoder.decode('AC')) // 29
+console.log(encoder.decode('ANE')) // 1045
+```
+
+```javascript
+const encoder = new AlphanumericEncoder()
+console.log(encoder.decode('a')) // undefined
+console.log(encoder.decode(123)) // undefined
+console.log(encoder.decode('A?')) // undefined
+```
+
+```javascript
+const encoder = new AlphanumericEncoder()
+encoder.dictionary = 'ABCD'
+console.log(encoder.decode('A')) // 1
+console.log(encoder.decode('AC')) // 7
+console.log(encoder.decode('ADBAC')) // 551
+console.log(encoder.decode('ANE')) // undefined
+```
 
-Returns **[string][7]** Dictionary encoded value
+Returns **[number][12]** Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`.
 
 [1]: #alphanumericencoder
 [2]: #dictionary
-[3]: #dictionary-1
-[4]: #parameters
+[3]: #parameters
+[4]: #examples
 [5]: #encode
 [6]: #parameters-1
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
-[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[7]: #examples-1
+[8]: #decode
+[9]: #parameters-2
+[10]: #examples-2
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
diff --git a/README.md b/README.md
@@ -63,9 +63,9 @@ npm install alphanumeric-encoder
 ### Use in Javascript
 
 ```javascript
-const alphanumericEncoder = require('alphanumeric-encoder')
+const AlphanumericEncoder = require('alphanumeric-encoder')
 
-const encoder = new alphanumericEncoder()
+const encoder = new AlphanumericEncoder()
 
 console.log(encoder.encode(5)) // 'E'
 console.log(encoder.encode(48)) // 'AV'
@@ -80,7 +80,7 @@ console.log(encoder.decode('ANE')) // 1045
 
 ## :gear: API Documentation
 
-See the [API](/../../blob/main/API.md) for more specific use information.
+See the [API](/../../blob/main/API.md) for more specific information on how to use the class.
 
 ## :hammer_and_wrench: Node and Operating System Support Policy
 

diff --git a/index.js b/index.js
@@ -1,24 +1,30 @@
 /**
  * A class for encoding and decoding base 10 integers to a custom alphanumeric base representation.
- *
  */
 class AlphanumericEncoder {
     constructor() {
+        /**
+         * @private
+         * @type {string}
+         */
         this._dictionary = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' // Default dictionary is the English alphabet, all capitalized, in order
     }
 
     /**
-     * Returns the current dictionary. Default is the English alphabet in order: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+     * Set or get the current dictionary.
      *
-     * @returns {string} The current dictionary in use
-     */
-    get dictionary() {
-        return this._dictionary
-    }
-
-    /**
+     * Default is the English alphabet in order: `ABCDEFGHIJKLMNOPQRSTUVWXYZ`
      *
-     * @param {string} newDictionary String of unique characters in order for the new dictionary
+     * @param {string} newDictionary (If setting) String of unique letters and numbers, in order, for the new dictionary
+     * @returns {string} (If used as getter) The current dictionary in use
+     *
+     * @example
+     * console.log(AlphanumericEncoder.dictionary)  // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+     *
+     * AlphanumericEncoder.dictionary = 'ABCD'
+     * console.log(AlphanumericEncoder.dictionary)  // 'ABCD'
+     *
+     * AlphanumericEncoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated
      */
     set dictionary(newDictionary) {
         // Check for empty dictionaries
@@ -50,15 +56,46 @@ class AlphanumericEncoder {
         this._dictionary = uppercaseDictionary
     }
 
+    get dictionary() {
+        return this._dictionary
+    }
+
     /**
      * Takes any number and converts it into a base (dictionary length) letter combo.
-     * It converts any numerical entry into a positive integer.
      *
-     * @param {number} number Base 10 number. Must be positive and non-zero. Decimals values are truncated.
+     * @param {number} integerToEncode Base 10 integer. If passed a non-integer number, decimal values are truncated.
+     * Passing zero, negative numbers, or non-numbers will return `undefined`.
      * @returns {string} Dictionary encoded value
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * console.log(encoder.encode(5)) // 'E'
+     * console.log(encoder.encode(48)) // 'AV'
+     * console.log(encoder.encode(733)) // 'ABE'
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * encoder.dictionary = 'ABCD'
+     * console.log(encoder.encode(5)) // 'AA'
+     * console.log(encoder.encode(48)) // 'BCD'
+     * console.log(encoder.encode(733)) // 'BCACA'
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * encoder.dictionary = 'DCBA'
+     * console.log(encoder.encode(5)) // 'DD'
+     * console.log(encoder.encode(48)) // 'CBA'
+     * console.log(encoder.encode(733)) // 'CBDBD'
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * encoder.dictionary = 'ABC123'
+     * console.log(encoder.encode(5)) // '2'
+     * console.log(encoder.encode(48)) // 'AA3'
+     * console.log(encoder.encode(733)) // 'CBBA'
      */
-    encode(number) {
-        if (Number.isNaN(number) || number < 0) {
+    encode(integerToEncode) {
+        if (Number.isNaN(integerToEncode) || integerToEncode < 0) {
             return undefined
         } //! Number.isInteger(number)
 
@@ -70,7 +107,7 @@ class AlphanumericEncoder {
             return dictionary.slice(num - 1, num)
         }
 
-        const baseNumber = Math.abs(Math.floor(number))
+        const baseNumber = Math.abs(Math.floor(integerToEncode))
 
         let index = baseNumber % this.dictionary.length
         let quotient = baseNumber / this.dictionary.length
@@ -93,10 +130,36 @@ class AlphanumericEncoder {
         return result + numToLetter(index, this.dictionary)
     }
 
-    decode(encoded) {
+    /**
+     * Takes any string and converts it into a base 10 integer based on the defined dictionary.
+     *
+     * @param {string} stringToDecode If passed a non-integer number, decimal values are truncated.
+     * Passing an empty string, `null`, or `undefined` will return `undefined`.
+     * @returns {number} Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`.
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * console.log(encoder.decode('A')) // 1
+     * console.log(encoder.decode('AC')) // 29
+     * console.log(encoder.decode('ANE')) // 1045
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * console.log(encoder.decode('a')) // undefined
+     * console.log(encoder.decode(123)) // undefined
+     * console.log(encoder.decode('A?')) // undefined
+     *
+     * @example
+     * const encoder = new AlphanumericEncoder()
+     * encoder.dictionary = 'ABCD'
+     * console.log(encoder.decode('A')) // 1
+     * console.log(encoder.decode('AC')) // 7
+     * console.log(encoder.decode('ADBAC')) // 551
+     * console.log(encoder.decode('ANE')) // undefined
+     */
+    decode(stringToDecode) {
         // Takes any number encoded with the provided encode dictionary
 
-        const safeEncoded = String(encoded) // += '' // Force any numbers passed into a string format to get proper behavior below
+        const safeEncoded = String(stringToDecode) // += '' // Force any numbers passed into a string format to get proper behavior below
 
         if (safeEncoded === '' || safeEncoded === null || safeEncoded === undefined) {
             return undefined