More SDK comments (#2796)

* sdk tweaks

* switch back to deeppartial

* WIP, update comments

* reinstall chesterton's fence

* more comments

* delete extra package.lock

* handle TODOs

---------

Co-authored-by: Aiden McClelland <me@drbonez.dev>

sdk/package/lib/mainFn/Daemons.ts

@@ -19,7 +19,22 @@ import { CommandController } from "./CommandController"
 export const cpExec = promisify(CP.exec)
 export const cpExecFile = promisify(CP.execFile)
 export type Ready = {
+  /** A human-readable display name for the health check. If null, the health check itself will be from the UI */
   display: string | null
+  /**
+   * @description The function to determine the health status of the daemon
+   * 
+   *   The SDK provides some built-in health checks. To see them, type sdk.healthCheck.
+   * 
+   * @example
+   * ```
+    fn: () =>
+      sdk.healthCheck.checkPortListening(effects, 80, {
+        successMessage: 'service listening on port 80',
+        errorMessage: 'service is unreachable',
+      })
+  * ```
+  */
   fn: (
     spawnable: ExecSpawnable,
   ) => Promise<HealthCheckResult> | HealthCheckResult
@@ -32,11 +47,23 @@ type DaemonsParams<
   Command extends string,
   Id extends string,
 > = {
+  /** The command line command to start the daemon */
   command: T.CommandType
-  image: { id: keyof Manifest["images"] & T.ImageId; sharedRun?: boolean }
+  /** Information about the image in which the daemon runs */
+  image: {
+    /** The ID of the image. Must be one of the image IDs declared in the manifest */
+    id: keyof Manifest["images"] & T.ImageId
+    /**
+     * Whether or not to share the `/run` directory with the parent container.
+     * This is useful if you are trying to connect to a service that exposes a unix domain socket or auth cookie via the `/run` directory
+     */
+    sharedRun?: boolean
+  }
+  /** For mounting the necessary volumes. Syntax: sdk.Mounts.of().addVolume() */
   mounts: Mounts<Manifest>
   env?: Record<string, string>
   ready: Ready
+  /** An array of IDs of prior daemons whose successful initializations are required before this daemon will initialize */
   requires: Exclude<Ids, Id>[]
   sigtermTimeout?: number
   onStdout?: (chunk: Buffer | string | any) => void

sdk/package/lib/mainFn/Mounts.ts

@@ -30,9 +30,13 @@ export class Mounts<Manifest extends T.SDKManifest> {
   }
 
   addVolume(
+    /** The ID of the volume to mount. Must be one of the volume IDs defined in the manifest */
     id: Manifest["volumes"][number],
+    /** The path within the volume to mount. Use `null` to mount the entire volume */
     subpath: string | null,
+    /** Where to mount the volume. e.g. /data */
     mountpoint: string,
+    /** Whether or not the volume should be readonly for this daemon */
     readonly: boolean,
   ) {
     this.volumes.push({
@@ -45,8 +49,11 @@ export class Mounts<Manifest extends T.SDKManifest> {
   }
 
   addAssets(
+    /** The ID of the asset directory to mount. This is typically the same as the folder name in your assets directory */
     id: Manifest["assets"][number],
+    /** The path within the asset directory to mount. Use `null` to mount the entire volume */
     subpath: string | null,
+    /** Where to mount the asset. e.g. /asset */
     mountpoint: string,
   ) {
     this.assets.push({
@@ -58,10 +65,15 @@ export class Mounts<Manifest extends T.SDKManifest> {
   }
 
   addDependency<DependencyManifest extends T.SDKManifest>(
+    /** The ID of the dependency service */
     dependencyId: keyof Manifest["dependencies"] & string,
+    /** The ID of the volume belonging to the dependency service to mount */
     volumeId: DependencyManifest["volumes"][number],
+    /** The path within the dependency's volume to mount. Use `null` to mount the entire volume */
     subpath: string | null,
+    /** Where to mount the dependency's volume. e.g. /service-id */
     mountpoint: string,
+    /** Whether or not the volume should be readonly for this daemon */
     readonly: boolean,
   ) {
     this.dependencies.push({

sdk/package/lib/test/inputSpecBuilder.test.ts

@@ -6,8 +6,6 @@ import { Variants } from "../../../base/lib/actions/input/builder/variants"
 import { ValueSpec } from "../../../base/lib/actions/input/inputSpecTypes"
 import { setupManifest } from "../manifest/setupManifest"
 import { StartSdk } from "../StartSdk"
-import { VersionGraph } from "../version/VersionGraph"
-import { VersionInfo } from "../version/VersionInfo"
 
 describe("builder tests", () => {
   test("text", async () => {