initial api jsdoc

.eslintrc

@@ -1,18 +1,16 @@
 {
   "root": true,
   "parser": "@typescript-eslint/parser",
-  "plugins": [
-    "@typescript-eslint",
-    "prettier"
-  ],
+  "plugins": ["@typescript-eslint", "prettier", "jsdoc"],
   "extends": [
     "eslint:recommended",
     "plugin:@typescript-eslint/eslint-recommended",
     "plugin:@typescript-eslint/recommended",
+    "plugin:jsdoc/recommended",
     "prettier"
   ],
   "rules": {
-    "no-console": 1,       // Means warning
+    "no-console": 1, // Means warning
     "prettier/prettier": 2 // Means error
   }
-}
+}

.github/workflows/pages.yml

@@ -33,9 +33,10 @@ jobs:
       - name: Install Node modules
         run: |
           npm install
-      - name: Build project
+      - name: Build example project and copy docs
         run: |
           npm run build
+          npm run genDocs
           cd examples/typescript
           npm install
           npm run build

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 lib
 bundle.js
+docs
 esptool-js-*.tgz
 .vscode/settings.json
 .parcel-cache

examples/typescript/.parcelrc

@@ -0,0 +1,7 @@
+{
+   "extends": "@parcel/config-default",
+   "resolvers": [
+     "parcel-resolver-ignore",
+     "..."
+   ]
+ }

examples/typescript/README.md

@@ -1,6 +1,8 @@
 # Using Esptool-JS in a Typescript environment
 
-This example has example code in `src/index.ts` which is called in the `index.html`. We are using Parcel to do bundle mechanism for the resulting JavaScript for simplicity here.
+This example has example code in `src/index.ts` which is called in the `index.html`. We are using Parcel to bundle resulting files for simplicity here.
+
+**NOTE:** This example is linked to the documentation generated from the source code. You could remove such dependency if necessary by remove `./docs/index.html` from `src/index.html` if you need so. NPM commands used below will generate documentation as well.
 
 ## Testing it locally
 
@@ -9,4 +11,13 @@ npm install
 npm run dev
 ```
 
-Then open http://localhost:1234 in Chrome or Edge. The `npm run dev` step will call Parcel which start a local http server serving `index.html` with compiled `index.ts`.
+Then open http://localhost:1234 in Chrome or Edge. The `npm run dev` step will call Parcel which start a local http server serving `index.html` with compiled `index.ts`.
+
+## Generate build to publish
+
+```
+npm install
+npm run build
+```
+
+Copy the content of `dist` to your static pages service like Github pages.

examples/typescript/package.json

@@ -4,15 +4,20 @@
   "description": "This an example of using esptool-js with parcel and typescript",
   "source": "src/index.html",
   "scripts": {
-    "dev": "parcel src/index.html",
-    "build": "npm run clean && parcel build src/index.html --no-optimize --public-url ./",
+    "genDocs": "cd ../.. && npm run genDocs && mkdir -p examples/typescript/dist && cp -r docs examples/typescript/dist && cd examples/typescript",
+    "dev": "npm run genDocs && parcel src/index.html",
+    "build": "npm run clean && npm run genDocs && parcel build src/index.html --no-optimize --public-url ./",
     "clean": "rimraf dist .parcel-cache",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "parcelIgnore": [
+    "./docs/.+"
+  ],
   "author": "",
   "license": "ISC",
   "devDependencies": {
     "parcel": "^2.8.3",
+    "parcel-resolver-ignore": "^2.1.5",
     "rimraf": "^4.1.2",
     "typescript": "^4.9.4"
   }

examples/typescript/src/index.html

@@ -20,6 +20,9 @@ <h1 align="center"><p><img src="../assets/esp-logo.png" width="42" height="42" s
         <h4 align="center">A Serial Flasher utility for Espressif chips</h4>
         <div id="safariErr" style="display:none"><p align="center" style="color:red">This tool is not supported on Safari browser!</p>
         </div>
+        <div align="center">
+            <a class="btn btn-info" href="./docs/index.html">View the API Documentation</a>
+          </div>
         <div class="container" id="main">
             <hr/>
             <div id="program">

examples/typescript/src/index.ts

@@ -38,6 +38,16 @@
 consoleStopButton.style.display = "none";
 filesDiv.style.display = "none";
 
+/**
+ * The built in Event object.
+ * @external Event
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Event}
+ */
+
+/**
+ * File reader handler to read given local file.
+ * @param {Event} evt File Select event
+ */
 function handleFileSelect(evt) {
   const file = evt.target.files[0];
 
@@ -78,16 +88,16 @@
     } as LoaderOptions;
     esploader = new ESPLoader(flashOptions);
 
-    chip = await esploader.main_fn();
+    chip = await esploader.main();
 
     // Temporarily broken
-    // await esploader.flash_id();
+    // await esploader.flashId();
   } catch (e) {
     console.error(e);
     term.writeln(`Error: ${e.message}`);
   }
 
   console.log("Settings done for :" + chip);
   lblBaudrate.style.display = "none";
   lblConnTo.innerHTML = "Connected to device: " + chip;
   lblConnTo.style.display = "block";
@@ -113,9 +123,9 @@
 eraseButton.onclick = async () => {
   eraseButton.disabled = true;
   try {
-    await esploader.erase_flash();
+    await esploader.eraseFlash();
   } catch (e) {
     console.error(e);
     term.writeln(`Error: ${e.message}`);
   } finally {
     eraseButton.disabled = false;
@@ -166,12 +176,24 @@
   }
 };
 
-function removeRow(row) {
+/**
+ * The built in HTMLTableRowElement object.
+ * @external HTMLTableRowElement
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableRowElement}
+ */
+
+/**
+ * Remove file row from HTML Table
+ * @param {HTMLTableRowElement} row Table row element to remove
+ */
+function removeRow(row: HTMLTableRowElement) {
   const rowIndex = Array.from(table.rows).indexOf(row);
   table.deleteRow(rowIndex);
 }
 
-// to be called on disconnect - remove any stale references of older connections if any
+/**
+ * Clean devices variables on chip disconnect. Remove stale references if any.
+ */
 function cleanUp() {
   device = null;
   transport = null;
@@ -215,7 +237,7 @@
       break;
     }
   }
   console.log("quitting console");
 };
 
 consoleStopButton.onclick = async () => {
@@ -228,7 +250,11 @@
   programDiv.style.display = "initial";
 };
 
-function validate_program_inputs() {
+/**
+ * Validate the provided files images and offset to see if they're valid.
+ * @returns {string} Program input validation result
+ */
+function validateProgramInputs() {
   const offsetArr = [];
   const rowCount = table.rows.length;
   let row;
@@ -258,7 +284,7 @@
 
 programButton.onclick = async () => {
   const alertMsg = document.getElementById("alertmsg");
-  const err = validate_program_inputs();
+  const err = validateProgramInputs();
 
   if (err != "success") {
     alertMsg.innerHTML = "<strong>" + err + "</strong>";
@@ -301,9 +327,9 @@
       },
       calculateMD5Hash: (image) => CryptoJS.MD5(CryptoJS.enc.Latin1.parse(image)),
     } as FlashOptions;
-    await esploader.write_flash(flashOptions);
+    await esploader.writeFlash(flashOptions);
   } catch (e) {
     console.error(e);
     term.writeln(`Error: ${e.message}`);
   } finally {
     // Hide progress bars and show erase buttons