Inline Documentation

Dagger Modules and Dagger Functions should be documented so that descriptions are shown in the API and the CLI - for example, when calling dagger functions and dagger call --help.

Module documentation

The following code snippet shows how to add high-level module documentation:

/**
 * This module returns information about the OS for a container image
 */
import { dag, object, func } from "@dagger.io/dagger"

@object()
class MyModule {
  @func()
  async version(): Promise<string> {
    return await dag
      .container()
      .from("alpine:3.14.0")
      .withExec(["/bin/sh", "-c", "cat /etc/os-release | grep VERSION_ID"])
      .stdout()
  }
}

Function documentation

The following code snippet shows how to add documentation for a function in your Dagger Module:

import { object, func } from "@dagger.io/dagger"

@object()
class MyModule {
  /**
   * Compute the sum of two numbers.
   *
   * Example usage: dagger call add --a=4 --b=5
   *
   * @param a The first number to add
   * @param b The second number to add
   */
  @func()
  add(a = 4, b: number): number {
    return a + b
  }
}

Here is an example of the result from dagger call add --help:

Compute the sum of two numbers.

Example usage: dagger call add --a=4 --b=5

Usage:
  dagger call add [flags]

EXPERIMENTAL:
  dagger call add is currently under development and may change in the future.

Flags:
      --a int   The first number to add (default 4)
      --b int   The second number to add

Object and field documentation

The following code snippet shows how to add documentation for an object and its fields in your Dagger Module:

import { object, field } from "@dagger.io/dagger"

/**
 * The Person object represents a single user of the system
 */
@object()
class Person {
  /**
   * The name of the person.
   */
  @field()
  name = "anonymous"

  /**
   * The age of the person.
   */
  @field()
  age: number

  constructor(age: number, name?: string) {
    this.name = name ?? this.name
    this.age = age
  }
}

Here is an example of the result from dagger functions:

Name   Description
age    The age of the person.
name   The name of the person.