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
- Python
- 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.
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)
}
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.
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."""
"""A function to say hello."""
@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}!"
"""A function to say a loud hello."""
@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()}!"
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()}!`
}
}
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
- Python
- TypeScript
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,
}
}
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[str, Doc("The age of the user.")]
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.
*/
age: number,
/**
* The age of the user.
*/
name: string,
) {
this.name = name
this.age = age
}
}
Here is an example of the result from dagger call --help
:
ARGUMENTS
--age string The age of the user. [required]
--name string The name of the user. [required]