docs: document the public API as TSDoc (generated from type declarations)

README.md

@@ -42,83 +42,7 @@ bare-make test
 
 ## API
 
-#### `await generate([options])`
-
-Options include:
-
-```js
-options = {
-  source: '.',
-  build: 'build',
-  platform: os.platform(),
-  arch: os.arch(),
-  simulator: false,
-  environment,
-  cache: true,
-  preset,
-  sanitize,
-  fuzz,
-  debug,
-  withDebugSymbols,
-  withMinimalSize,
-  define,
-  cwd: path.resolve('.'),
-  color: false,
-  verbose: false,
-  stdio
-}
-```
-
-#### `await build([options])`
-
-Options include:
-
-```js
-options = {
-  build: 'build',
-  target,
-  clean: false,
-  parallel,
-  preset,
-  cwd: path.resolve('.'),
-  verbose: false,
-  stdio
-}
-```
-
-#### `await install([options])`
-
-Options include:
-
-```js
-options = {
-  build: 'build',
-  prefix: 'prebuilds',
-  component,
-  link: false,
-  strip: false,
-  parallel,
-  cwd: path.resolve('.'),
-  verbose: false,
-  stdio
-}
-```
-
-#### `await test([options])`
-
-Options include:
-
-```js
-options = {
-  build: 'build',
-  timeout: 30,
-  parallel,
-  preset,
-  cwd: path.resolve('.'),
-  verbose: false,
-  stdio
-}
-```
+See the [`bare-make` reference](https://docs.pears.com/reference/bare/modules/bare-make).
 
 ## CLI
 

lib/build.d.ts

@@ -1,16 +1,30 @@
 import Pipe from 'bare-pipe'
 
+/** Options for `build()`. */
 declare interface BuildOptions {
+  /** Path to the build tree (default `'build'`, unset when `preset` is given). */
   build?: string
+  /** Clean before building (default `false`). */
   clean?: boolean
+  /** Working directory the build runs in (default the process working directory). */
   cwd?: string
+  /** Number of parallel jobs; `0` lets the build system decide (default `0`). */
   parallel?: number
+  /** CMake preset to use (default none). */
   preset?: string
+  /** Standard I/O configuration passed to the CMake subprocess. */
   stdio?: Pipe
+  /** The target to build (default all targets). */
   target?: string
+  /** Enable verbose output (default `false`). */
   verbose?: boolean
 }
 
+/**
+ * @param opts - Options; `build` defaults to `'build'` (unset when `preset` is set), `parallel` to
+ * `0`, and `clean` and `verbose` to `false`.
+ * @throws {BUILD_FAILED} the build exits with a non-zero status.
+ */
 declare function build(opts?: BuildOptions): Promise<void>
 
 declare namespace build {

lib/errors.d.ts

@@ -1,10 +1,37 @@
 declare class MakeError extends Error {
+  /**
+   * Construct a `MakeError` with the given message and `code`.
+   * @param msg - Human-readable error message.
+   * @param code - The error code, assigned to `err.code`.
+   * @param fn - The function to omit from the captured stack trace (default the `MakeError`
+   * constructor).
+   */
   constructor(msg: string, code: string, fn?: MakeError)
 
+  /**
+   * Create a `MakeError` with code `'UNKNOWN_TOOLCHAIN'`.
+   * @param msg - Human-readable error message.
+   */
   static UNKNOWN_TOOLCHAIN(msg: string): MakeError
+  /**
+   * Create a `MakeError` with code `'GENERATE_FAILED'`.
+   * @param msg - Human-readable error message.
+   */
   static GENERATE_FAILED(msg: string): MakeError
+  /**
+   * Create a `MakeError` with code `'BUILD_FAILED'`.
+   * @param msg - Human-readable error message.
+   */
   static BUILD_FAILED(msg: string): MakeError
+  /**
+   * Create a `MakeError` with code `'INSTALL_FAILED'`.
+   * @param msg - Human-readable error message.
+   */
   static INSTALL_FAILED(msg: string): MakeError
+  /**
+   * Create a `MakeError` with code `'TEST_FAILED'`.
+   * @param msg - Human-readable error message.
+   */
   static TEST_FAILED(msg: string): MakeError
 }
 

lib/generate.d.ts

@@ -1,25 +1,53 @@
 import Pipe from 'bare-pipe'
 
+/** Options for `generate()`. */
 declare interface GenerateOptions {
+  /** Architecture to build for (default the host architecture). */
   arch?: string
+  /** Path to the build tree (default `'build'`, unset when `preset` is given). */
   build?: string
+  /** Reuse the build variable cache; set to `false` to configure fresh (default `true`). */
   cache?: boolean
+  /** Working directory the generation runs in (default the process working directory). */
   cwd?: string
+  /** Configure a debug build (default `false`). */
   debug?: boolean
+  /**
+   * Build variable cache entries to create or update, as `<var>[:<type>]=<value>` strings (default
+   * `[]`).
+   */
   define?: string[]
+  /** The environment to build for (default none). */
   environment?: string
+  /** Configure for fuzzing (default `false`). */
   fuzz?: boolean
+  /** Operating system platform to build for (default the host platform). */
   platform?: string
+  /** CMake preset to use (default none). */
   preset?: string
+  /** Sanitizer to enable (default none). */
   sanitize?: string
+  /** Build for a simulator (default `false`). */
   simulator?: boolean
+  /** Path to the source tree (default `'.'`). */
   source?: string
+  /** Standard I/O configuration passed to the CMake subprocess. */
   stdio?: Pipe
+  /** Enable verbose output (default `false`). */
   verbose?: boolean
+  /** Configure a release build with debug symbols (default `false`). */
   withDebugSymbols?: boolean
+  /** Configure a release build with minimal size (default `false`). */
   withMinimalSize?: boolean
 }
 
+/**
+ * @param opts - Options; `source` defaults to `'.'`, `build` to `'build'`, `platform` and `arch` to
+ * the host, `cache` to `true`, and the build-type flags (`debug`, `fuzz`, `withDebugSymbols`,
+ * `withMinimalSize`, `verbose`) to `false`.
+ * @throws {UNKNOWN_TOOLCHAIN} no toolchain is available for the resolved `platform`-`arch` target.
+ * @throws {GENERATE_FAILED} build system generation exits with a non-zero status.
+ */
 declare function generate(opts?: GenerateOptions): Promise<void>
 
 declare namespace generate {

lib/install.d.ts

@@ -1,17 +1,32 @@
 import Pipe from 'bare-pipe'
 
+/** Options for `install()`. */
 declare interface InstallOptions {
+  /** Path to the build tree (default `'build'`). */
   build?: string
+  /** The component to install (default all components). */
   component?: string
+  /** Working directory the install runs in (default the process working directory). */
   cwd?: string
+  /** Symlink rather than copy the installed files (default `false`). */
   link?: boolean
+  /** Whether to install in parallel (default `false`). */
   parallel?: boolean
+  /** The prefix to install to (default `'prebuilds'`). */
   prefix?: string
+  /** Standard I/O configuration passed to the CMake subprocess. */
   stdio?: Pipe
+  /** Strip symbols before installing (default `false`). */
   strip?: boolean
+  /** Enable verbose output (default `false`). */
   verbose?: boolean
 }
 
+/**
+ * @param opts - Options; `build` defaults to `'build'`, `prefix` to `'prebuilds'`, and `link`,
+ * `strip`, and `verbose` to `false`.
+ * @throws {INSTALL_FAILED} the install exits with a non-zero status.
+ */
 declare function install(opts?: InstallOptions): Promise<void>
 
 declare namespace install {

lib/test.d.ts

@@ -1,15 +1,28 @@
 import Pipe from 'bare-pipe'
 
+/** Options for `test()`. */
 declare interface TestOptions {
+  /** Path to the build tree (default `'build'`). */
   build?: string
+  /** Working directory the tests run in (default the process working directory). */
   cwd?: string
+  /** Number of parallel jobs; a negative value lets the runner decide (default `-1`). */
   parallel?: number
+  /** CMake preset to use (default none). */
   preset?: string
+  /** Standard I/O configuration passed to the CMake subprocess. */
   stdio?: Pipe
+  /** Default per-test timeout in seconds (default `30`). */
   timeout?: number
+  /** Enable verbose output (default `false`). */
   verbose?: boolean
 }
 
+/**
+ * @param opts - Options; `build` defaults to `'build'`, `timeout` to `30` seconds, `parallel` to
+ * `-1`, and `verbose` to `false`.
+ * @throws {TEST_FAILED} one or more tests fail.
+ */
 declare function test(opts?: TestOptions): Promise<void>
 
 declare namespace test {