Add inline documentation for most functions

packages/nodejs/project.bri

@@ -5,6 +5,12 @@ export const project = {
   version: "20.14.0",
 };
 
+/**
+ * The main Node.js recipe. Returns a recipe containing the following:
+ *
+ * - `bin/node`
+ * - `bin/npm`
+ */
 function nodejs(): std.Recipe<std.Directory> {
   let node = std
     .download({
@@ -29,6 +35,33 @@ interface NpmInstallOptions {
   npmPackage: std.AsyncRecipe<std.Directory>;
 }
 
+/**
+ * Install the dependencies from an NPM package. Returns a recipe containing
+ * everything from the package, plus a `node_modules` directory.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import * as std from "std";
+ * import nodejs, { npmInstall } from "nodejs";
+ *
+ * export default () => {
+ *   // Get all the files for the NPM package
+ *   let npmPackage = Brioche.glob("src", "package.lock", "package.json");
+ *
+ *   // Install the dependencies
+ *   npmPackage = npmInstall({ npmPackage });
+ *
+ *   // Run the build script and save the output from `dist/`
+ *   return std.runBash`
+ *     npm run build
+ *     mv dist "$BRIOCHE_OUTPUT"
+ *   `
+ *     .workDir(npmPackage)
+ *     .dependencies(nodejs());
+ * };
+ * ```
+ */
 export function npmInstall(
   options: NpmInstallOptions,
 ): std.Recipe<std.Directory> {

packages/rust/project.bri

@@ -29,6 +29,14 @@ const Manifest = t.object({
   profiles: t.record(t.string(), t.array(t.string())),
 });
 
+/**
+ * The main Rust recipe. Returns a recipe containing the following:
+ *
+ * - `bin/rustc`
+ * - `bin/cargo`
+ *
+ * ...among other binaries.
+ */
 async function rust(): Promise<std.Recipe<std.Directory>> {
   const manifestToml = await std
     .download({
@@ -112,9 +120,30 @@ export interface CargoBuildOptions {
   runnable?: string;
 }
 
+/**
+ * Build a Cargo crate. Defaults to the release profile. Calls
+ * `cargo install` internally, and returns the contents of `$CARGO_INSTALL_ROOT`
+ *
+ * ## Options
+ *
+ * - `crate`: The crate to build.
+ * - `runnable`: Optionally set a path to the binary to run
+ *   by default (e.g. `bin/foo`).
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { cargoBuild } from "rust";
+ *
+ * export default () => {
+ *   return cargoBuild({
+ *     crate: Brioche.glob("src", "Cargo.*"),
+ *     runnable: "bin/hello",
+ *   });
+ * };
+ * ```
+ */
 export function cargoBuild(options: CargoBuildOptions) {
-  const toolchain = options.toolchain ?? std.toolchain();
-
   // Create a skeleton crate so we have enough information to vendor the
   // dependencies
   const skeletonCrate = createSkeletonCrate(options.crate);

packages/std/core/global.bri

@@ -7,8 +7,78 @@ import {
 import { source } from "./source.bri";
 
 export interface BriocheGlobal {
+  /**
+   * Include a file from the filesystem. The path is relative to the
+   * current Brioche module, and cannot go outside the project root.
+   *
+   * ## Example
+   *
+   * ```
+   * project/
+   * ├── project.bri
+   * └── file.txt
+   * ```
+   *
+   * ```typescript
+   * // project.bri
+   *
+   * // Returns a file recipe with the contents of `file.txt`
+   * const file = Brioche.includeFile("file.txt");
+   * ```
+   */
   includeFile(path: string): Recipe<File>;
+
+  /**
+   * Include a directory from the filesystem. The path is relative to the
+   * current Brioche module, and cannot go outside the project root.
+   *
+   * ## Example
+   *
+   * ```
+   * project/
+   * ├── project.bri
+   * └── src/
+   *    ├── fizz.txt
+   *    └── buzz.txt
+   * ```
+   *
+   * ```typescript
+   * // project.bri
+   *
+   * // Returns a directory containing `fizz.txt` and `buzz.txt`
+   * const file = Brioche.includeDirectory("src");
+   * ```
+   */
   includeDirectory(path: string): Recipe<Directory>;
+
+  /**
+   * Include multiple files from the filesystem using a glob pattern. The
+   * returned directory structure preserves the relative paths of the files,
+   * relative to the current Brioche module. The glob pattern will not
+   * match any paths if it tries going outside the current module directory.
+   *
+   * ## Example
+   *
+   * ```
+   * project/
+   * ├── project.bri
+   * ├── hello.txt
+   * └── src/
+   *    ├── foo.txt
+   *    └── secretfile.env
+   * ```
+   *
+   * ```typescript
+   * // project.bri
+   *
+   * // Returns a directory with this structure:
+   * // .
+   * // ├── hello.txt
+   * // └── src/
+   * //    └── foo.txt
+   * const file = Brioche.glob("hello.txt, src/*.txt")
+   * ```
+   */
   glob(...patterns: string[]): Recipe<Directory>;
 }
 

packages/std/core/recipes/directory.bri

@@ -9,6 +9,20 @@ import {
 } from "./recipe.bri";
 import { artifactType } from "./artifact_type.bri";
 
+/**
+ * Constructs a new directory. Takes an object argument, where each key
+ * is a filename and each value is a recipe
+ *
+ * ## Example
+ *
+ * ```typescript
+ * std.directory({
+ *   "hello": std.directory({
+ *     "world.txt": std.file("Hello, world!"),
+ *   }),
+ * });
+ * ```
+ */
 export function directory(
   entries: Record<string, AsyncRecipe> = {},
 ): Recipe<Directory> {
@@ -37,6 +51,10 @@ export function directory(
   });
 }
 
+/**
+ * Perform a deep merge of two or more directories. The rightmost directory
+ * takes precedence.
+ */
 export function merge(
   ...directories: AsyncRecipe<Directory>[]
 ): Recipe<Directory> {

packages/std/core/recipes/download.bri

@@ -7,6 +7,20 @@ export interface DownloadOptions {
   hash: Hash;
 }
 
+/**
+ * Returns a recipe that will download a URL, and return
+ * a file of its results. A has must be provided, and will
+ * be used to verify the downloaded contents.
+ *
+ * ## Example
+ *
+ * std.download({
+ *   url: "https://gist.githubusercontent.com/kylewlacy/c0f1a43e2641686f377178880fcce6ae/raw/f48155695445aa218e558fba824b61cf718d5e55/lorem-ipsum.txt",
+ *   hash: std.sha256Hash(
+ *     "642e3f58cc2bcc0d12d2e1e21dd9ea131f058a98e23e9beac79881bb0a324d06"
+ *   ),
+ * });
+ */
 export function download(opts: DownloadOptions): Recipe<File> {
   return createRecipe(["file"], {
     sourceDepth: 1,

packages/std/core/recipes/file.bri

@@ -3,6 +3,15 @@ import { assert } from "../utils.bri";
 import { type Recipe, createRecipe, fileRecipeUtils } from "./recipe.bri";
 import { artifactType } from "./artifact_type.bri";
 
+/**
+ * Create a new file, which contains the provided content.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * std.file("Hello, world!");
+ * ```
+ */
 export function file(content: string | Uint8Array): Recipe<File> {
   const serializedContent = runtime.bstring(content);
   return createRecipe(["file"], {

packages/std/core/recipes/hash.bri

@@ -1,6 +1,10 @@
 import * as runtime from "../runtime.bri";
 import { assert } from "../utils.bri";
 
+/**
+ * Represents an expected SHA-256 hash. Should be a hex-encoded
+ * string of 64 characters.
+ */
 export function sha256Hash(value: string): Sha256Hash {
   assert(runtime.isHex(value));
   return new Sha256Hash(value);

packages/std/core/recipes/process.bri

@@ -23,13 +23,72 @@ export interface ProcessUnsafe {
 export type Process = Recipe & ProcessUtils;
 
 export interface ProcessUtils {
+  /**
+   * Returns a new process with more environment variables set.
+   */
   env(values: Record<string, ProcessTemplateLike>): Process;
+
+  /**
+   * Returns a new process with more dependencies added. The new
+   * dependencies take precedence over the old ones.
+   */
   dependencies(...dependencies: AsyncRecipe<Directory>[]): Process;
+
+  /**
+   * Returns a new process with a different working directory.
+   */
   workDir(workDir: AsyncRecipe<Directory>): Process;
+
+  /**
+   * Returns a new process with a different output scaffold.
+   */
   outputScaffold(outputScaffold: AsyncRecipe): Process;
+
+  /**
+   * Returns a new process with unsafe options set.
+   */
   unsafe(unsafeOptions: ProcessUnsafe): Process;
 }
 
+/**
+ * Create a recipe that will run a process, returning the contents that
+ * the process writes to the path `$BRIOCHE_OUTPUT`. The process can
+ * write a file, directory, or symlink to this path.
+ *
+ * Most options can be passed as a string literal, or as a template using
+ * the template function `std.tpl`. Recipes in the template will be
+ * expanded to an absolute path when the process runs.
+ *
+ * ## Options
+ *
+ * These options can be passed when calling `std.process()`, or can be
+ * set by calling methods on another process recipe (these methods are
+ * **immutable**, so make sure to assign the result to a variable!)
+ *
+ * - `command`: The command to run. Should either be a template, or a
+ *   string referencing a command from `dependencies`.
+ * - `args`: An array of arguments to pass to the command.
+ * - `env`: An object containing environment variables to set for the process.
+ * - `dependencies`: An array of dependencies to call the process with.
+ *   Dependencies will be merged into the process's environment.
+ * - `workDir`: Set to a directory recipe that will be copied into the
+ *   process's starting working directory.
+ * - `outputScaffold`: Set to a recipe that will be be used to initialize
+ *   `$BRIOCHE_OUTPUT`, which the process can then manipulate.
+ * - `unsafe`: Set to `true` to use unsafe options. You must take extra
+ *   care to ensure that running the process is hermetic when using these
+ *   options! The following options are available:
+ *   - `networking`: Set to `true` to allow the process to access the network.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * // Call Bash and write "Hello world!" to the output path
+ * std.process({
+ *   command: std.tpl`${std.tools()}/bin/bash`,
+ *   args: ["-c", 'echo "Hello world!" > "$BRIOCHE_OUTPUT"'],
+ * });
+ */
 export function process(options: ProcessOptions): Process {
   const env: Record<string, ProcessTemplateLike> = {
     BRIOCHE_OUTPUT: outputPath,
@@ -131,6 +190,11 @@ export function processTemplate(
   return new ProcessTemplate(...components);
 }
 
+/**
+ * Create a process template, which can be used to include recipe paths
+ * or other pre-defined values for the command, arguments, or environment
+ * variables for a process.
+ */
 export function tpl(
   strings: TemplateStringsArray,
   ...items: ProcessTemplateLike[]
@@ -147,11 +211,42 @@ export function tpl(
   return new ProcessTemplate(...components);
 }
 
+/**
+ * Expands to the path where the process should write its output. Equivalent
+ * to the default environment variable `$BRIOCHE_OUTPUT`.
+ */
 export const outputPath: unique symbol = Symbol("outputPath");
+
+/**
+ * Expands to the directory where the process can write resources to that
+ * can then be referenced by files in the process's output. Equivalent
+ * to the default environment variable `$BRIOCHE_RESOURCE_DIR`.
+ */
 export const resourceDir: unique symbol = Symbol("resourceDir");
+
+/**
+ * Expands to a `:`-delimited list of directories where the process can find
+ * resources from its inputs. These directories are normally read-only.
+ * Equivalent to the default environment variable `$BRIOCHE_INPUT_RESOURCE_DIRS`.
+ */
 export const inputResourceDirs: unique symbol = Symbol("inputResourceDirs");
+
+/**
+ * Expands to the home directory when the process runs. Equivalent to the
+ * default environment variable `$HOME`.
+ */
 export const homeDir: unique symbol = Symbol("homeDir");
+
+/**
+ * Expands to the the "work directory" of the process. This is the directory
+ * a process starts in by default (which is usually `$HOME/work`).
+ */
 export const workDir: unique symbol = Symbol("workDir");
+
+/**
+ * Expands to the temporary directory where the process can write temporary
+ * files. Equivalent to the default environment variable `$TMPDIR`.
+ */
 export const tempDir: unique symbol = Symbol("tempDir");
 
 export type ProcessTemplateLike = Awaitable<ProcessTemplateComponent>;