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.

Go

The following code snippet shows how to add documentation for:

• The whole module
• Function methods
• Function arguments

// A simple example module to say hello.

// Further documentation for the module here.

package main

import (
	"fmt"
	"strings"
)

type MyModule struct{}

// Return a greeting.
func (m *MyModule) Hello(
	// Who to greet
	name string,
	// The greeting to display
	greeting string,
) string {
	return fmt.Sprintf("%s, %s!", greeting, name)
}

// Return a loud greeting.
func (m *MyModule) LoudHello(
	// Who to greet
	name string,
	// The greeting to display
	greeting string,
) string {
	out := fmt.Sprintf("%s, %s!", greeting, name)
	return strings.ToUpper(out)
}

Python

The following code snippet shows how to use Python's documentation string conventions for adding descriptions to:

• The whole module or package
• Object type classes (group of functions)
• Function methods
• Function arguments

For function arguments, annotate with the dagger.Doc metadata.

note

dagger.Doc is just an alias for typing_extensions.Doc.

"""A simple example module to say hello.

Further documentation for the module here.
"""

from typing import Annotated

from dagger import Doc, function, object_type


@object_type
class MyModule:
    """Simple hello functions."""

    @function
    def hello(
        self,
        name: Annotated[str, Doc("Who to greet")],
        greeting: Annotated[str, Doc("The greeting to display")],
    ) -> str:
        """Return a greeting."""
        return f"{greeting}, {name}!"

    @function
    def loud_hello(
        self,
        name: Annotated[str, Doc("Who to greet")],
        greeting: Annotated[str, Doc("The greeting to display")],
    ) -> str:
        """Return a loud greeting.

        Loud means all caps.
        """
        return f"{greeting.upper()}, {name.upper()}!"

TypeScript

The following code snippet shows how to add documentation for:

• The whole module
• Function methods
• Function arguments

/**
 * A simple example module to say hello.
 *
 * Further documentation for the module here.
 */
import { object, func } from "@dagger.io/dagger"

@object()
class MyModule {
  /**
   * Return a greeting.
   *
   * @param name Who to greet
   * @param greeting The greeting to display
   */
  @func()
  hello(name: string, greeting: string): string {
    return `${greeting}, ${name}!`
  }

  /**
   * Return a loud greeting.
   *
   * @param name Who to greet
   * @param greeting The greeting to display
   */
  @func()
  loudHello(name: string, greeting: string): string {
    return `${greeting.toUpperCase()}, ${name.toUpperCase()}!`
  }
}

PHP

The following code snippet shows how to add documentation for:

• The whole module
• Function methods
• Function arguments

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\{DaggerObject, DaggerFunction, Doc};

#[DaggerObject]
#[Doc('A simple example module to say hello.')]
class MyModule
{
    #[DaggerFunction]
    #[Doc('Return a greeting')]
    public function hello(
        #[Doc('Who to greet')]
        string $name,
        #[Doc('The greeting to display')]
        string $greeting
    ): string {
        return "{$greeting} {$name}";
    }

    #[DaggerFunction]
    #[Doc('Return a loud greeting')]
    public function loudHello(
        #[Doc('Who to greet')]
        string $name,
        #[Doc('The greeting to display')]
        string $greeting
    ): string {
        return strtoupper("{$greeting} {$name}");
    }
}

Here is an example of the result from dagger functions:

Name         Description
hello        Return a greeting.
loud-hello   Return a loud greeting.

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

Return a greeting.

USAGE
  dagger call hello [arguments]

ARGUMENTS
      --greeting string   The greeting to display [required]
      --name string       Who to greet [required]

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

Go

package main

// The struct represents a single user of the system.
type MyModule struct {
	Name string
	Age  int
}

func New(
	// The name of the user.
	name string,
	// The age of the user.
	age int,
) *MyModule {
	return &MyModule{
		Name: name,
		Age:  age,
	}
}

Python

from typing import Annotated

from dagger import Doc, object_type


@object_type
class MyModule:
    """The object represents a single user of the system."""

    name: Annotated[str, Doc("The name of the user.")]
    age: Annotated[int, Doc("The age of the user.")]

TypeScript

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

/**
 * The object represents a single user of the system.
 */
@object()
class MyModule {
  @func()
  name: string
  @func()
  age: number

  constructor(
    /**
     * The name of the user.
     */
    name: string,
    /**
     * The age of the user.
     */
    age: number,
  ) {
    this.name = name
    this.age = age
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\{DaggerObject, DaggerFunction, Doc};

#[DaggerObject]
#[Doc('The object represents a single user of the system.')]
class MyModule
{
    #[DaggerFunction]
    public function __construct(
        #[Doc('The name of the user.')]
        private string $name,
        #[Doc('The age of the user.')]
        private int $age,
    ) {
    }
}

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

ARGUMENTS
      --age int       The age of the user. [required]
      --name string   The name of the user. [required]