wip: updating jsdoc comments

[ci skip]

Author: tegefaulkes

.gitlab-ci.yml

@@ -166,45 +166,6 @@ build:linux:
     # Runs on tag pipeline where the tag is a prerelease or release version
     - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+(?:-.*[0-9]+)?$/
 
-build:windows:
-  stage: build
-  needs: []
-  allow_failure: true
-  tags:
-    - windows
-  variables:
-    # Only x64 architecture is needed
-    npm_config_arch: "x64"
-    RUST_BACKTRACE: "1"
-    LIBCLANG_PATH: "C:\\Program Files\\LLVM\\bin"
-  before_script:
-    - mkdir -Force "$CI_PROJECT_DIR/tmp"
-    - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1
-  script:
-    - ./scripts/choco-install.ps1
-    - refreshenv
-    - npm install --ignore-scripts
-    - $env:Path = "$(npm root)\.bin;" + $env:Path
-    - npm run prebuild --verbose -- --production
-    - npm test -- --ci --coverage
-    - npm run bench
-  artifacts:
-    when: always
-    reports:
-      junit:
-        - ./tmp/junit/junit.xml
-      coverage_report:
-        coverage_format: cobertura
-        path: ./tmp/coverage/cobertura-coverage.xml
-      metrics: ./benches/results/metrics.txt
-    paths:
-      - ./prebuild/
-  rules:
-    # Runs on staging commits and ignores version commits
-    - if: $CI_COMMIT_BRANCH == 'staging' && $CI_COMMIT_TITLE !~ /^[0-9]+\.[0-9]+\.[0-9]+(?:-.*[0-9]+)?$/
-    # Runs on tag pipeline where the tag is a prerelease or release version
-    - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+(?:-.*[0-9]+)?$/
-
 build:macos:
   stage: build
   needs: []

scripts/choco-install.ps1

@@ -7,7 +7,23 @@ import process from 'process';
 import path from 'path';
 
 interface Exec {
-  execvpe(cmd: string, argv: Array<string>, envv: Array<string>): undefined;
+  /**
+   * This calls the provided command with the provided arguments. The env variable are also provided in the format of
+   * 'key=value'. If the call fails in any way then it just throws the error code 'Error('number')`. The most common
+   * would be an `ENOENT` in the form of `Error('2')`.
+   *
+   * This will replace the current process with the provided cmd. From the callers perspective this will seem really odd
+   * and never return. The call can not return so and code after it is unreachable, hence the `never` return type. So
+   * treat this function as a termination of the process, much like a `process.exit()` call.
+   *
+   * The exec'ed program will not assume the environment of the current process. This can allow isolation but if you
+   * want to have the current environment then you'll have to pass it in manually through the envp parameter.
+   *
+   * @param cmd - the command to call, this can be anything in the PATH or a specific file
+   * @param argv - The args to be passed to the command
+   * @param envp - env variables that you want to provide. These are formatted as an array of 'key=value'
+   */
+  execvpe(cmd: string, argv: Array<string>, envp: Array<string>): never;
 }
 
 const projectRoot = path.join(__dirname, '../');