doc: document errors

Add js-docs to document errors. Some functions throw the same type of error for different reasons. These should probably get different error types, or better represent their errors as part of their return-type. This is a first step to get an overview over the apps errors.

src/cmd-add.ts

@@ -37,6 +37,9 @@ type AddResult = {
   code: ResultCode;
 };
 
+/**
+ * @throws Error An unhandled error occurred
+ */
 export const add = async function (
   pkgs: PackageReference | PackageReference[],
   options: AddOptions

src/cmd-deps.ts

@@ -13,6 +13,9 @@ export type DepsOptions = CmdOptions<{
   deep?: boolean;
 }>;
 
+/**
+ * @throws Error An unhandled error occurred
+ */
 export const deps = async function (
   pkg: PackageReference,
   options: DepsOptions

src/cmd-login.ts

@@ -28,6 +28,9 @@ export type LoginOptions = CmdOptions<{
   alwaysAuth?: boolean;
 }>;
 
+/**
+ * @throws Error An unhandled error occurred
+ */
 export const login = async function (options: LoginOptions) {
   // parse env
   const env = await parseEnv(options, false);
@@ -114,6 +117,7 @@ const npmLogin = async function (
 
 /**
  * Write npm token to .npmrc
+ * @throws Error An unhandled error occurred
  */
 const writeNpmToken = async function (registry: RegistryUrl, token: string) {
   const configPath = getNpmrcPath();
@@ -131,6 +135,7 @@ const writeNpmToken = async function (registry: RegistryUrl, token: string) {
 
 /**
  * Return .npmrc config file path
+ * @throws Error Home-path could not be determined
  */
 export const getNpmrcPath = function () {
   const dirPath = process.env.USERPROFILE
@@ -179,6 +184,7 @@ export const generateNpmrcLines = function (
 
 /**
  * Write npm token to Unity
+ * @throws Error The specified authentication information was missing
  */
 const writeUnityToken = async function (
   configDir: string,

src/registry-client.ts

@@ -63,6 +63,9 @@ type NameVersionPair = {
   version: SemanticVersion | "latest" | undefined;
 };
 
+/**
+ * @throws AssertionError The given parameter is not a {@link NpmClientError}
+ */
 export function assertIsNpmClientError(
   x: unknown
 ): asserts x is NpmClientError {

src/types/editor-version.ts

@@ -40,6 +40,7 @@ export type EditorVersion = {
  * Compares two editor versions for ordering
  * @param a The first version
  * @param b The second version
+ * @throws Error An editor version could not be parsed
  */
 export const compareEditorVersion = function (
   a: string,

src/types/registry-url.ts

@@ -38,6 +38,7 @@ export function removeTrailingSlash(registry: RegistryUrl): RegistryUrl {
  * - Prepending http if it is missing
  * - Removing trailing slashes
  * @param s The string
+ * @throws assert.AssertionError if string does not have valid format
  */
 export function coerceRegistryUrl(s: string): RegistryUrl {
   if (!s.toLowerCase().startsWith("http")) s = "http://" + s;

src/utils/env.ts

@@ -40,7 +40,10 @@ export type Env = {
   editorVersion: string | null;
 };
 
-// Parse env
+/**
+ * Parse env
+ * @throws Error An unhandled error occurred
+ */
 export const parseEnv = async function (
   options: CmdOptions,
   checkPath: boolean

src/utils/error-type-guards.ts

@@ -2,6 +2,9 @@ import { HttpErrorBase } from "npm-registry-fetch";
 import { AssertionError } from "assert";
 import ErrnoException = NodeJS.ErrnoException;
 
+/**
+ * @throws AssertionError The given parameter is not an error
+ */
 export function assertIsError(x: unknown): asserts x is ErrnoException {
   if (!(x instanceof Error))
     throw new AssertionError({

src/utils/upm-config-io.ts

@@ -13,6 +13,7 @@ const configFileName = ".upmconfig.toml";
  * Gets the path to directory in which the upm config is stored
  * @param wsl Whether WSL should be treated as Windows
  * @param systemUser Whether to authenticate as a Windows system-user
+ * @throws Error Could not determine upm config directory
  */
 export const getUpmConfigDir = async (
   wsl: boolean,