docs: more jsdocs (#214)

Author: dsherret

mod.ts

@@ -104,6 +104,7 @@ export type $Type<TExtras extends ExtrasObject = {}> =
     : Omit<$BuiltInProperties<TExtras>, keyof TExtras>)
   & TExtras;
 
+/** String literal template. */
 export interface $Template {
   (strings: TemplateStringsArray, ...exprs: any[]): CommandBuilder;
 }
@@ -124,6 +125,7 @@ type Which = typeof import("./src/deps.ts").which;
  */
 type WhichSync = typeof import("./src/deps.ts").whichSync;
 
+/** Collection of built-in properties that come with a `$`. */
 export interface $BuiltInProperties<TExtras extends ExtrasObject = {}> {
   /**
    * Makes a request to the provided URL throwing by default if the
@@ -590,6 +592,7 @@ export interface Create$Options<TExtras extends ExtrasObject> {
   commandBuilder?: CommandBuilder;
   /** Uses the state of this request builder as a starting point. */
   requestBuilder?: RequestBuilder;
+  /** Extra properties to put on the `$`. */
   extras?: TExtras;
 }
 

src/pipes.ts

@@ -5,22 +5,25 @@ import type { RequestBuilder } from "./request.ts";
 
 const encoder = new TextEncoder();
 
+/** `Deno.Reader` stream. */
 export interface Reader {
   read(p: Uint8Array): Promise<number | null>;
 }
 
-export interface Writer {
-  write(p: Uint8Array): Promise<number>;
-}
-
+/** `Deno.WriterSync` stream. */
 export interface WriterSync {
   writeSync(p: Uint8Array): number;
 }
 
+/** `Deno.Closer` */
 export interface Closer {
   close(): void;
 }
 
+/** Behaviour to use for stdin.
+ * @value "inherit" - Sends the stdin of the process to the shell (default).
+ * @value "null" - Does not pipe or redirect the pipe.
+ */
 export type ShellPipeReaderKind =
   | "inherit"
   | "null"

src/result.ts

@@ -17,14 +17,19 @@ export function getAbortedResult(): ExecuteResult {
 
 /** Tells the shell it should exit immediately with the provided exit code. */
 export interface ExitExecuteResult {
+  /** Discriminator. */
   kind: "exit";
+  /** Exit code to use and completely exit the shell with. */
   code: number;
 }
 
 /** Tells the shell to continue executing. */
 export interface ContinueExecuteResult {
+  /** Discriminator. */
   kind: "continue";
+  /** Exit code to use. */
   code: number;
+  /** Changes to the shell that should occur (ex. unsetting env vars). */
   changes?: EnvChange[];
 }
 
@@ -39,8 +44,11 @@ export type EnvChange = SetEnvVarChange | SetShellVarChange | UnsetVarChange | C
  * Used for registering custom commands.
  */
 export interface SetEnvVarChange {
+  /** Discriminator. */
   kind: "envvar";
+  /** Name of the env var to set. */
   name: string;
+  /** Value to set the env var to. */
   value: string;
 }
 
@@ -49,8 +57,11 @@ export interface SetEnvVarChange {
  * Used for registering custom commands.
  */
 export interface SetShellVarChange {
+  /** Discriminator. */
   kind: "shellvar";
+  /** Name of the shell var to set. */
   name: string;
+  /** Value to set the shell var to. */
   value: string;
 }
 
@@ -59,7 +70,9 @@ export interface SetShellVarChange {
  * Used for registering custom commands.
  */
 export interface UnsetVarChange {
+  /** Discriminator. */
   kind: "unsetvar";
+  /** Nave of the env var to unset. */
   name: string;
 }
 
@@ -68,6 +81,8 @@ export interface UnsetVarChange {
  * Used for registering custom commands.
  */
 export interface CdChange {
+  /** Discriminator. */
   kind: "cd";
+  /** Relative or absolute directory to change to. */
   dir: string;
 }