Add module docs, throws, examples, categories and cross links

.eslintrc.cjs

@@ -68,6 +68,7 @@ module.exports = {
     "jsdoc/require-returns-description": "error",
     "jsdoc/no-blank-blocks": "error",
     "jsdoc/require-description-complete-sentence": "error",
+    "jsdoc/require-throws-description": "error",
     "@typescript-eslint/ban-ts-comment": "warn",
     "@typescript-eslint/camelcase": "off",
     "@typescript-eslint/explicit-function-return-type": "off",

package-lock.json

@@ -29,6 +29,7 @@
         "husky": "^9.1.7",
         "prettier": "^3.8.1",
         "typedoc": "^0.28.17",
+        "typedoc-plugin-coverage": "^4.0.2",
         "typescript": "^5.9.3",
         "vitest": "^4.1.0"
       }
@@ -3916,6 +3917,19 @@
         "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x"
       }
     },
+    "node_modules/typedoc-plugin-coverage": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/typedoc-plugin-coverage/-/typedoc-plugin-coverage-4.0.2.tgz",
+      "integrity": "sha512-mfn0e7NCqB8x2PfvhXrtmd7KWlsNf1+B2N9y8gR/jexXBLrXl/0e+b2HdG5HaTXGi7i0t2pyQY2VRmq7gtdEHQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 18"
+      },
+      "peerDependencies": {
+        "typedoc": "0.28.x"
+      }
+    },
     "node_modules/typedoc/node_modules/brace-expansion": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",

package.json

@@ -61,6 +61,7 @@
     "husky": "^9.1.7",
     "prettier": "^3.8.1",
     "typedoc": "^0.28.17",
+    "typedoc-plugin-coverage": "^4.0.2",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   }

src/base-tools/index.ts

@@ -1,3 +1,12 @@
+/**
+ * @module base-tools
+ * Tool provider registry. Collects {@link types.IToolProvider} strategies
+ * for installing or updating conda, mamba, python, and conda-build in the
+ * `base` environment.
+ *
+ * @category Base Tools
+ */
+
 import * as types from "../types";
 
 import * as core from "@actions/core";

src/base-tools/update-conda-build.ts

@@ -1,3 +1,11 @@
+/**
+ * @module base-tools/update-conda-build
+ * Tool provider for installing or pinning `conda-build` in the `base`
+ * environment.
+ *
+ * @category Base Tools
+ */
+
 import * as types from "../types";
 import * as utils from "../utils";
 

src/base-tools/update-conda.ts

@@ -1,3 +1,10 @@
+/**
+ * @module base-tools/update-conda
+ * Tool provider for installing or pinning `conda` in the `base` environment.
+ *
+ * @category Base Tools
+ */
+
 import * as types from "../types";
 import * as utils from "../utils";
 

src/base-tools/update-mamba.ts

@@ -1,3 +1,12 @@
+/**
+ * @module base-tools/update-mamba
+ * Tool provider for installing or pinning `mamba` in the `base` environment,
+ * including post-install steps to ensure the `mamba` CLI is available in
+ * `condabin` on both Unix and Windows.
+ *
+ * @category Base Tools
+ */
+
 import * as fs from "fs";
 import * as path from "path";
 

src/base-tools/update-python.ts

@@ -1,3 +1,11 @@
+/**
+ * @module base-tools/update-python
+ * Tool provider for installing or pinning `python` in the `base` environment
+ * when the activation target is `base`.
+ *
+ * @category Base Tools
+ */
+
 import * as types from "../types";
 import * as utils from "../utils";
 

src/conda.ts

@@ -1,3 +1,11 @@
+/**
+ * @module conda
+ * High-level helpers for locating, running, and configuring a conda or
+ * mamba installation, including shell initialization and `.condarc` management.
+ *
+ * @category Core
+ */
+
 //-----------------------------------------------------------------------
 // Conda helpers
 //-----------------------------------------------------------------------
@@ -100,6 +108,7 @@ export function condaExecutableLocations(
  * @param options - The current dynamic options.
  * @param subcommand - If provided, mamba is only used when it supports this subcommand.
  * @returns The absolute path to the found executable.
+ * @throws {Error} If no conda or mamba executable exists at any candidate location.
  */
 export function condaExecutable(
   inputs: types.IActionInputs,
@@ -146,6 +155,18 @@ export function isMambaInstalled(
  * @param options - The current dynamic options.
  * @param captureOutput - When `true`, returns stdout as a string.
  * @returns The captured stdout if `captureOutput` is `true`, otherwise void.
+ * @throws {Error} If the command exits with a non-zero return code.
+ *
+ * @example
+ * ```ts
+ * // Install numpy into the active env
+ * await condaCommand(["install", "numpy"], inputs, options);
+ *
+ * // Capture JSON config output
+ * const json = await condaCommand(
+ *   ["config", "--show", "--json"], inputs, options, true
+ * );
+ * ```
  */
 export async function condaCommand(
   cmd: string[],

src/constants.ts

@@ -1,3 +1,11 @@
+/**
+ * @module constants
+ * Platform detection flags, URL prefixes, architecture maps, and other
+ * compile-time values shared across the action.
+ *
+ * @category Core
+ */
+
 import * as os from "os";
 import * as path from "path";
 

src/delete.ts

@@ -1,3 +1,11 @@
+/**
+ * @module delete
+ * Post-action cleanup entry point. Removes extracted packages from the
+ * conda cache to reduce artifact size on GitHub Actions runners.
+ *
+ * @category Core
+ */
+
 import * as fs from "fs";
 import * as path from "path";
 

src/env/explicit.ts

@@ -1,3 +1,11 @@
+/**
+ * @module env/explicit
+ * Create a conda environment from an explicit lockfile generated by
+ * `conda list --explicit` or `conda-lock`.
+ *
+ * @category Environments
+ */
+
 import * as types from "../types";
 import * as conda from "../conda";
 import * as outputs from "../outputs";

src/env/index.ts

@@ -1,3 +1,12 @@
+/**
+ * @module env
+ * Environment provider registry. Iterates through
+ * {@link types.IEnvProvider} strategies to create or update the target
+ * conda environment from explicit lockfiles, YAML specs, or simple specs.
+ *
+ * @category Environments
+ */
+
 import * as path from "path";
 import * as fs from "fs";
 
@@ -35,6 +44,7 @@ const ENV_PROVIDERS: types.IEnvProvider[] = [
  * @param inputs - The parsed action inputs.
  * @param options - The current dynamic options.
  * @returns Resolves when the environment has been created or updated.
+ * @throws {Error} If no {@link types.IEnvProvider} can handle the given inputs.
  */
 export async function ensureEnvironment(
   inputs: types.IActionInputs,

src/env/simple.ts

@@ -1,3 +1,11 @@
+/**
+ * @module env/simple
+ * Create a conda environment with `conda create` when no environment file
+ * is provided, optionally pinning `python-version`.
+ *
+ * @category Environments
+ */
+
 import * as core from "@actions/core";
 
 import * as types from "../types";

src/env/yaml.ts

@@ -1,3 +1,11 @@
+/**
+ * @module env/yaml
+ * Create or update a conda environment from a YAML `environment.yml` file,
+ * optionally patching dependencies (for example, pinning `python-version`).
+ *
+ * @category Environments
+ */
+
 import * as fs from "fs";
 import * as path from "path";
 

src/input.ts

@@ -1,3 +1,11 @@
+/**
+ * @module input
+ * Parsing, validation, and normalization of action inputs from the
+ * workflow `with` block into a frozen {@link types.IActionInputs} object.
+ *
+ * @category Core
+ */
+
 import * as path from "path";
 import * as core from "@actions/core";
 import * as semver from "semver";
@@ -112,7 +120,8 @@ const RULES: IRule[] = [
 /**
  * Parse, validate, and normalize string-ish inputs from a workflow action's `with`.
  *
- * @returns The frozen, validated action inputs object.
+ * @returns The frozen, validated {@link types.IActionInputs} object.
+ * @throws {Error} If any validation rule fails.
  */
 export async function parseInputs(): Promise<types.IActionInputs> {
   let arch = core.getInput("architecture") || process.arch;

src/installer/base.ts

@@ -1,3 +1,11 @@
+/**
+ * @module installer/base
+ * Shared logic for downloading, caching, and locating `constructor`-compatible
+ * installers via the `@actions/tool-cache`.
+ *
+ * @category Installers
+ */
+
 import * as crypto from "crypto";
 import * as path from "path";
 import { URL, fileURLToPath } from "url";
@@ -19,6 +27,17 @@ import * as types from "../types";
  *
  * @param options - Cache and download metadata for the installer.
  * @returns The local path to the installer (with the correct extension).
+ * @throws {Error} If no executable path could be determined after all attempts.
+ *
+ * @example
+ * ```ts
+ * const localPath = await ensureLocalInstaller({
+ *   url: "https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh",
+ *   tool: "Miniconda3",
+ *   version: "latest",
+ *   arch: "x86_64",
+ * });
+ * ```
  */
 export async function ensureLocalInstaller(
   options: types.ILocalInstallerOpts,

src/installer/bundled-miniconda.ts

@@ -1,3 +1,11 @@
+/**
+ * @module installer/bundled-miniconda
+ * Use the pre-bundled Miniconda installation already present on the
+ * GitHub Actions runner image, avoiding any download or install step.
+ *
+ * @category Installers
+ */
+
 import * as types from "../types";
 import { MINICONDA_DIR_PATH } from "../constants";
 

src/installer/download-miniconda.ts

@@ -1,3 +1,11 @@
+/**
+ * @module installer/download-miniconda
+ * Download Miniconda installers from `repo.anaconda.com` using the
+ * well-known directory listing to resolve available versions.
+ *
+ * @category Installers
+ */
+
 import * as fs from "fs";
 
 import * as core from "@actions/core";
@@ -43,6 +51,8 @@ async function minicondaVersions(arch: string): Promise<string[]> {
  * @param pythonMajorVersion - The Python major version for the installer (e.g. `3`).
  * @param inputs - The parsed action inputs containing version and architecture.
  * @returns The local path to the downloaded installer.
+ * @throws {Error} If the architecture is not in {@link constants.MINICONDA_ARCHITECTURES}.
+ * @throws {Error} If the requested version is not found in the available versions list.
  */
 export async function downloadMiniconda(
   pythonMajorVersion: number,

src/installer/download-miniforge.ts

@@ -1,3 +1,11 @@
+/**
+ * @module installer/download-miniforge
+ * Download Miniforge installers from GitHub releases using the well-known
+ * release URL structure of the `conda-forge/miniforge` repository.
+ *
+ * @category Installers
+ */
+
 import * as core from "@actions/core";
 
 import * as types from "../types";
@@ -12,6 +20,7 @@ import * as base from "./base";
  * @param inputs - The parsed action inputs containing variant, version, and architecture.
  * @param options - The current dynamic options.
  * @returns The local path to the downloaded installer.
+ * @throws {Error} If the architecture is not in {@link constants.MINIFORGE_ARCHITECTURES}.
  */
 export async function downloadMiniforge(
   inputs: types.IActionInputs,

src/installer/download-url.ts

@@ -1,3 +1,11 @@
+/**
+ * @module installer/download-url
+ * Download a `constructor`-compatible installer from an arbitrary URL,
+ * including `file://` URLs for locally-available installers.
+ *
+ * @category Installers
+ */
+
 import * as types from "../types";
 
 import * as base from "./base";

src/installer/index.ts

@@ -1,3 +1,12 @@
+/**
+ * @module installer
+ * Installer provider registry and runner. Iterates through
+ * {@link types.IInstallerProvider} strategies to locate or download a
+ * `constructor`-compatible installer, then executes it.
+ *
+ * @category Installers
+ */
+
 import * as path from "path";
 
 import * as core from "@actions/core";
@@ -40,6 +49,7 @@ const INSTALLER_PROVIDERS: types.IInstallerProvider[] = [
  * @param inputs - The parsed action inputs.
  * @param options - The current dynamic options.
  * @returns The installer result with the local path and updated options.
+ * @throws {Error} If no {@link types.IInstallerProvider} matches the given inputs.
  */
 export async function getLocalInstallerPath(
   inputs: types.IActionInputs,
@@ -64,6 +74,7 @@ export async function getLocalInstallerPath(
  * @param inputs - The parsed action inputs.
  * @param options - The current dynamic options.
  * @returns The updated dynamic options reflecting the new installation.
+ * @throws {Error} If the installer has an unknown file extension.
  */
 export async function runInstaller(
   installerPath: string,

src/outputs.ts

@@ -1,5 +1,8 @@
 /**
+ * @module outputs
  * Modify environment variables and action outputs.
+ *
+ * @category Core
  */
 import * as path from "path";
 

src/setup.ts

@@ -1,3 +1,12 @@
+/**
+ * @module setup
+ * Main entry point for the action. Orchestrates installer selection,
+ * conda configuration, shell initialization, base tool installation,
+ * and target environment creation.
+ *
+ * @category Core
+ */
+
 import * as fs from "fs";
 
 import * as core from "@actions/core";
@@ -15,7 +24,8 @@ import * as baseTools from "./base-tools";
  * Orchestrate the full conda setup: install, configure, init shell
  * integration, install base tools, and create the target environment.
  *
- * @param inputs - The parsed action inputs.
+ * @param inputs - The parsed {@link types.IActionInputs}.
+ * @throws {Error} If no conda `base` environment is found after installation.
  */
 async function setupMiniconda(inputs: types.IActionInputs): Promise<void> {
   let options: types.IDynamicOptions = {

src/utils.ts

@@ -1,3 +1,11 @@
+/**
+ * @module utils
+ * Low-level helpers for running shell commands, building conda package
+ * specs, and working with package directories.
+ *
+ * @category Core
+ */
+
 import * as os from "os";
 import * as path from "path";
 import * as stream from "stream";
@@ -56,6 +64,17 @@ export function isBaseEnv(envName: string) {
  * @param env - Additional environment variables to merge with `process.env`.
  * @param captureOutput - When `true`, returns stdout as a string instead of void.
  * @returns The captured stdout string if `captureOutput` is `true`, otherwise void.
+ * @throws {Error} If the command exits with a non-zero return code.
+ * @throws {Error} If stdout contains any substring in {@link constants.FORCED_ERRORS}.
+ *
+ * @example
+ * ```ts
+ * // Run conda info
+ * await execute(["conda", "info", "--json"]);
+ *
+ * // Capture output
+ * const output = await execute(["conda", "info", "--json"], {}, true);
+ * ```
  */
 export async function execute(
   command: string[],
@@ -114,6 +133,13 @@ export async function execute(
  * @param pkg - The package name.
  * @param spec - The version spec, optionally prefixed with an operator.
  * @returns A formatted `pkg=spec` or `pkg<operator>spec` string.
+ *
+ * @example
+ * ```ts
+ * makeSpec("python", "3.11");       // "python=3.11"
+ * makeSpec("conda", ">=23.1");      // "conda>=23.1"
+ * makeSpec("numpy", "1.24|1.25");   // "numpy1.24|1.25"
+ * ```
  */
 export function makeSpec(pkg: string, spec: string) {
   if (spec.match(/[=<>!\|]/)) {

typedoc.json

@@ -9,5 +9,16 @@
   "excludeInternal": true,
   "skipErrorChecking": true,
   "readme": "none",
-  "name": "setup-miniconda"
+  "name": "setup-miniconda",
+  "categorizeByGroup": true,
+  "categoryOrder": [
+    "Core",
+    "Installers",
+    "Environments",
+    "Base Tools",
+    "Types",
+    "*"
+  ],
+  "plugin": ["typedoc-plugin-coverage"],
+  "coverageLabel": "docs"
 }