docs: source code docs

fixes SAP-archive#12

Author: bd82

.eslintrc.js

@@ -2,9 +2,8 @@ module.exports = {
   // Common settings for JS Files.
   extends: [
     "eslint:recommended",
-    // TODO: inspect: https://mysticatea.github.io/eslint-plugin-eslint-comments/rules/require-description.html usage.
     "plugin:eslint-comments/recommended",
-    // Disables all formatting related rules as formatting is handled by prettier.
+    // Disables all formatting related rules as formatting is handled by prettier, not eslint.
     "prettier",
   ],
   parserOptions: {
@@ -17,14 +16,16 @@ module.exports = {
     mocha: true,
     node: true,
   },
+  rules: {
+    "eslint-comments/require-description": ["error", { ignore: [] }],
+  },
   overrides: [
     {
       // For pure-java script sub-packages and general scripts (in any package).
       files: ["*.js"],
     },
     {
-      // TODO: does this also  scan d.ts files?
-      // For sub-packages using TypeScript (libraries/VSCode Exts).
+      // For sub-packages using TypeScript (libraries/VSCode Exts) && TypeScript definitions (d.ts)
       files: ["*.ts"],
       plugins: ["@typescript-eslint"],
       parser: "@typescript-eslint/parser",

README.md

@@ -73,7 +73,7 @@ The consumption process is currently a **manual** step by step guide.
 1. Adjust the [.eslintrc.js](./.eslintrc.js) configuration.
 
    - Remove `overrides` sections for no longer relevant file types:
-     - `["*.ts"]` --> if your monorepo does not contain any TypeScript projects.
+     - `["*.ts"]` --> if your monorepo does not contain any TypeScript sources (including `.d.ts` files).
      - `["*.vue"]` --> if your monorepo does not contain any vue frontend projects.
    - Remove `dev-depedencies` from the [root package.json](./package.json)
      - `@typescript-eslint/*` --> if your monorepo does not contain any TypeScript projects.

packages/npm_package_javascript_library/.mocharc.js

@@ -1,7 +1,3 @@
-/**
- * A new Mocha configuration is needed because the JavaScript test files are located
- * in a different folder in a pure ECMAScript project.
- */
 module.exports = {
   spec: "./test/**/*spec.js",
 };

packages/npm_package_typescript_library/test/implementation-matches-public-api.ts

@@ -8,13 +8,13 @@ type AssertIsSubSet<SUBSET extends SUPERSET, SUPERSET> = [SUBSET, SUPERSET];
 // We can perform logical assertions on the API vs Impel
 // using discrete math semantics (subsets/supersets)
 // See: https://www.typescriptlang.org/docs/handbook/type-compatibility.html
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the definition is also the usage
 type EnsureAllDeclaredAreExposedAtRuntime = AssertIsSubSet<
   typeof implementation,
   typeof publicApi
 >;
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the definition is also the usage
 type EnsureNoRedundantAreExposedAtRuntime = AssertIsSubSet<
   typeof publicApi,
   typeof implementation

packages/vscode_simple_ext/src/extension.ts

@@ -1,4 +1,5 @@
 import { window } from "vscode";
+// Using **sibling** libraries from our monorepo.
 import { multiply } from "@ecmascript_monorepo_template/npm_package_javascript_library";
 import { add } from "@ecmascript_monorepo_template/npm_package_typescript_library";
 

packages/vue_frontend_rpc/local-dev/backend-mock.js

@@ -6,6 +6,13 @@ const {
 
 const ASYNC_NOOP = async () => {};
 
+/**
+ * A Backend mock using WebSockets.
+ * Note that this class does not include the RPC end points logic.
+ * Those can be passed via the constructors `opts` to implement different types of backend mocks, e.g:
+ * - In Memory mock for testing.
+ * - Mock using a real (hard-coded path) file for local "playground".
+ */
 class BackendMock {
   /**
    * @param [opts] {object}

packages/vue_frontend_rpc/local-dev/fs-backend-mock.js packages/vue_frontend_rpc/local-dev/run-fs-backend-mock.js

@@ -6,6 +6,10 @@ const editorFilePath = resolve(__dirname, "./person-details.json");
 const editorFileText = readFileSync(editorFilePath, "utf-8");
 let editorFileObject = JSON.parse(editorFileText);
 
+/**
+ * Websocket Backend mock using a real file (`./person-details.json`)
+ * This is used as a playground during local development to enable fast feedback loops.
+ */
 new BackendMock({
   onFrontendReady: async () => {
     return editorFileObject;

packages/vue_frontend_rpc/package.json

@@ -12,7 +12,7 @@
     "test": "vue-cli-service test:unit ./test/**/*spec.js",
     "coverage": "nyc vue-cli-service test:unit ./test/**/*spec.js",
     "serve": "vue-cli-service serve --port=8090",
-    "backend:mock": "node local-dev/fs-backend-mock.js"
+    "backend:mock": "node local-dev/run-fs-backend-mock.js"
   },
   "dependencies": {
     "core-js": "^3.6.5",

packages/vue_frontend_rpc/src/components/person-form.vue

@@ -77,9 +77,9 @@ export default {
   methods: {
     // we cannot test VSCode related flow without VSCode.
     setupVSCodeRpc: /* istanbul ignore next  */ function () {
-      // TODO: comment `acquireVsCodeApi` can only be called once.
+      // `acquireVsCodeApi()` can only be invoked once, so we are "saving" it's result
+      // on the `window` object in case we will need it again.
       window.vscode = acquireVsCodeApi();
-      // TODO: why does this constructor needs to be passed the window object?
       rpc = new RpcBrowser(window, window.vscode);
     },
 

packages/vue_frontend_rpc/test/fix-debugging.spec.js

@@ -1,5 +1,7 @@
-// During tests sources are compiled on the fly
-// This debugger statement provides our IDE with a little grace period
-// so it will be able to attach the breakpoints in time.
-// eslint-disable-next-line no-debugger
+/**
+ * During tests sources are compiled on the fly
+ * This debugger statement provides our IDE with a little grace period
+ * so it will be able to attach the breakpoints in time.
+ */
+// eslint-disable-next-line no-debugger -- see above block comment
 debugger;

packages/vue_frontend_rpc/test/functional/initial-data-visualization.spec.js

@@ -12,6 +12,7 @@ describe("The Person Form", () => {
 
     before(async () => {
       port = await getPort({ port: getPort.makeRange(9000, 10000) });
+      // Start an in-memory websocket backend mock for this test.
       backendMock = new BackendMock({
         port: port,
         onFrontendReady: async () => {
@@ -32,6 +33,10 @@ describe("The Person Form", () => {
       // - Enable awaiting for the initialization logic as it seems
       //   we cannot "await" for Vue life-cycle methods (e.g created) in tests.
       await wrapper.vm.setupWsRPC(port);
+
+      // Inspect the frontend successfully invoked `onFrontendReady` and received the expected data back.
+      // - Note this is an (almost) productive functional flow, not a pure unit test.
+      //   We have a real frontend and backend communicating with RPC over a websocket.
       const firstNameInput = wrapper.find("#firstName");
       expect(firstNameInput.element.value).to.eql("Jane");
       const lastNameInput = wrapper.find("#lastName");

packages/vue_frontend_rpc/test/functional/saving-new-data.spec.js

@@ -9,6 +9,10 @@ describe("The Person Form", () => {
   describe("saving new data flow", () => {
     let backendMock;
     let port;
+    // Our backend and frontend both run under the same node.js process in this test.
+    // However as they communicate with RPC over websockets they don't share the same "promise chains".
+    // We use a deferred promise to resolve async waiting during the tests.
+    // Other approaches are documented here: https://vue-test-utils.vuejs.org/guides/#testing-asynchronous-behavior
     let saveDeferred = pDefer();
 
     before(async () => {
@@ -52,6 +56,9 @@ describe("The Person Form", () => {
       await countryInput.setValue("SadLand");
       const saveButton = wrapper.find("#saveButton");
       saveButton.trigger("click");
+      //   Inspect the backend successfully received the expected data on `save` rpc call.
+      // - Note this is an (almost) productive functional flow, not a pure unit test.
+      //   We have a real frontend and backend communicating with RPC over a websocket.
       await saveDeferred.promise;
     });
 

scripts/merge-coverage.js

@@ -1,5 +1,7 @@
 /**
- * based on https://github.com/istanbuljs/istanbuljs/blob/1fe490e51909607137ded25b1688581c9fd926cd/monorepo-merge-reports.js
+ * This script will create a **merged** coverage reports from all sub-packages.
+ * This report will can be found at the root `coverage` dir and will also be uploaded to coveralls.io
+ * - based on https://github.com/istanbuljs/istanbuljs/blob/1fe490e51909607137ded25b1688581c9fd926cd/monorepo-merge-reports.js
  */
 const { dirname, basename, join, resolve } = require("path");
 const { spawnSync } = require("child_process");
@@ -35,6 +37,7 @@ glob.sync("packages/*/.nyc_output").forEach((nycOutput) => {
   }
 });
 
+// Create merged report
 const { status, stderr } = spawnSync(
   resolve("node_modules", ".bin", "nyc"),
   ["report", "--reporter=lcov"],

webpack.config.vscode.base.js

@@ -11,7 +11,7 @@ const config = {
   target: "node",
   devtool: "source-map",
   resolve: {
-    // Solution for sibling package resolution inside mono-repo
+    // Solution for sibling package resolution inside a monorepo
     modules: [
       path.resolve(__dirname, "node_modules"),
       path.resolve(__dirname, "../node_modules"),